Global Variables

In ResSim, a Global Variable is a data object that modelers can use to represent data needed or produced by their model and its scripts. Input Global Variables are assigned values through the Alternative Editor when defining an alternative.  Output Global Variables are defined during through a script during the compute. The intention of global variables is to allow an operation to be specified in the abstract (say through rules and state variables) and defined with different parameters for each alternative.

For example, a modeler may want to study the effect of changing a threshold on operations – rather than making copies of a rule and changing it, creating a new operation set for each copy of the rule, and a new alternative for each, the modeler can create one rule, one operations set, and vary the value of the threshold as a global variable in the alternative.   This simplifies the modeling process and reduces the number of model components that need to be updated if a change is required, such as in the priority of rules in the operations set.  Eliminating the number of operations sets and copies of rules that are required makes the model easier to maintain and can make the modeler more confident in their results.

A second reason to use Global Variables is for defining commonly changed parameters in scripted rules and state variables – by defining the input as a Global Variable, the modeler developing the scripts can expose these input controls in a manner that avoids later editing the scripts, and allows for the same value to be passed to several scripts at once.  In both real-time modeling and studies modeling, this allows the configuration parameters to be specified by other modelers who may not be as comfortable with the scripting editor.  The input Global Variables allow for several types input validation, reducing the amount of checks for bad values that need to be implemented in the script.  For example, in a real-time model, several rules may require the outcome of a calculation using parameters determined during weekly coordination calls with another agency.  In this case, the modeler who built the model would create a Global Variable to represent the input values for the calculation, and the real-time modelers would adjust their value in the copy of the alternative used in their forecast.  Then during the compute, a State Variable script (or scripted rule) would calculate release requirements from the values of the Global Variables.

Finally, the Global Variables feature enhances ResSim capabilities in linked modeling environments such as the CWMS CAVI and HEC-WAT.  In this case, both input and output global variables can be linked between models, allowing data not represented by a time-series to be passed in a standard format.

NEW IN RESSIM 3.5The initial implementation of Global Variables was done in ResSim version 3.5. This functionality is limited to using Global Variables in scripts (except for Time Series Global Variables). There are plans for expanded functionality in future versions, as funding becomes available, with the objective of being able to define any component of the operations with a Global Variable.

Background

As modelers began to create more and more sophisticated and complex models, they were forced to employ creative "modeling techniques" or workarounds to specify information for the model that might vary per alternative.  Since these "modeling techniques" usually involved using ResSim features in ways they were not intended, the models became harder to understand without clear and complete accompanying documentation.  Global Variables were created to replace the use of the various modeling techniques with clear and specific variables that modelers could use as they needed.  Global variables will provide the ResSim modeler more flexibility in defining external data that will be provided to the model and/or data that the model will produce as output.  Listed below are several reasons why global variables are superior to the workarounds used in the past.

Time Blocking Loses Scripted Variables Stacks

• State variables rely on localTimeSeries and vars stacks within the script to maintain a holding place for data.  However, since memory is finite, the data is lost.  With Global Variables, users have a data object that they can write to and then access later.

External Time Series Require "Dummy Rules"

• Currently, when a scripted rule or state variable requires an external time series that is not calculated by the model, it must be imported using a "dummy rule."  The "dummy rule" identifies an "external Variable" so that an entry associated with that desired time series will be available inside of the alternative editor.  The use of a Global Variable allows ResSim to store the time series in an object without requiring the dummy rule to be present in the Operation Set and makes it more clear where the input timeseries is defined and how it is used.

Single Value ("Scalar") Inputs

• When operations (rules, if-blocks, diversions, and guide curves) are a function of a value that comes from an external source, a "dummy rule" may be created to identify and store the value in a time series or by using a time series pathname.  The other way to previously do this was to create a state variable whose sole purpose was to initialize with the desired value to be called upon by other scripts.

Overview

As defined above, a global variable is a data object that a user can create to provide custom data to their model or to contain data for output from their model.   The definition or configuration of a global variable is stored as part of a reservoir network.  Once created, the global variable can be accessed by any ResSim object that is designed to access global variables.  Currently, only scripted rules and state variables can access all types of global variables, but global time-series variables can be accessed by anything that can access a model variable, state variable, or external variable.

Global Variables are not assigned their values when they are created.  Input global variables are assigned their values in the alternative editor as part of the definition of an alternative.   Output global variables can only be assigned their values by a scripted rule or state variable designed to fulfill that purpose.

Usage Type - Input or Output

Global Variables were designed to have an intended usage type - Input or Output. 

• Input global variables will be assigned their value as part of the definition of an alternative. As described in the Alternative's section, the alternative stores its configuration in a set of files.  With the addition of global variables, a new pair of files - altname.igv and altname.dss have been added to the set of alternative files.  
• Output global variables will be assigned their value by the model, during a compute - usually by a scripted rule or state variable.

Common Attributes

All global variables are specified by a name, usage type, and whether or not they are a Data Location. 

• Name The name is used to identify the Global Variable across various interfaces and to access it in scripts. 
• Usage Type As stated above, the global variable should be specified as either input or output.
• Data Location Being designated as a Data Location will enable the global variable to be linked to other models in HEC-WAT and CWMS CAVI model sequences. 
• Description Optionally, a description may be entered, as a free-form text field where additional details about the global variable can be documented. 
• Parameter Type Some global variable types require a parameter, such as "flow", "elevation", or "percent" among others.  This is used to tell the model what kind of data it represents and ensure the variable is used appropriately.

Types of Global Variables

Although the most common variable type that modelers have employed through "modeling techniques" is time series, other types were also needed including scalars (single valued variables), strings, and tables.  This led to the selection of the four global variable types called for in the original design - Time Series, Scalars, Strings, and Tables.  A fifth global variable type - External - was added during implementation when two separate data objects were identified that could not be represented with the original four types.  External Global Variables are a generic data "placeholder" for any data object that the modeler wants to write their own plugin to create, store, manage, and supply to ResSim.

Time Series Global Variables

A time series global variable represents time series data, just like ResSim model variables and external variables.  In fact, since the means for creating/identifying external variables is somewhat "hidden" in ResSim (and, behind the scenes, their implementation is less than ideal), Time Series global variables are a replacement for the External Variables that can be selected at various places by the Independent Variable Selector.  External Variables are still available in ResSim 3.5, but Time Series Global Variables are recommended for use whenever a time series input is required at more than one operational element (rule, if-block, zone, diversion) or used by a scripted rule or State Variable (instead of a dummy rule).

A time series global variable can be used where ever a model variable, state variable, or external variable can be used.  This includes as the independent variable using the Independent Variable Selector for a lookup table in a rule, zone, diversion, or as a variable in a conditional expression of an IF-Block.  Using the scripting API, they may be used as a dependency (input) to a state variable or scripted rule or as an output calculated by the script.

When defining a Time Series Global Variable, the parameter type must be selected.

Scalar Global Variables

A scalar global variable represents a single value or unit of data.  A scalar variable could represent the size of a water account, a trigger elevation of a flashboarded spillway, the start date of a forecast period, or any value that will be constant for the alternative but may be different between one alternative and other.  

A scalar global variable has the most options for specifying the attributes of the variable.  Besides giving it a name, usage (input or output) and description, the variable must be assigned a data type. 

The data type of a scalar global variable can be integer, double, boolean, date, time, date and time, day-of-week, seasonal date, or month-of-year. Integer and decimal data types require a parameter type to be specified.  Then, depending on the selected data type, optional attributes may include a minimum value, a maximum value, or a selection list, which restricts the inputs to a limited list defined by the modeler.

String Global Variables

A String global variable holds a string, a sequence of characters.  The string could be a file name, a drought level, or whatever your model needs.  String global input variables may be useful for identifying a filename for a script to use to retrieve alternative specific data, but they could also be used to specify a condition or state that a script might need to control operations.  String global output variables can be used to hold a message or provide information to the modeler or to another model.

String global variables can be set using the whole ASCII character set or can be restricted to only alphabetic or alphanumeric characters.  In addition, the user can specify a list of invalid characters to further restrict what characters can be used to specify the value of the string variable.  Alternatively, the user can specify a selection list of strings from which the user or a script can select the desired value for the string, restricting the input to a pre-defined list.

Table Global Variables

A table global variable holds an array of values.  Table global variables can be used to bring a lookup table - like a rule curve or a storage reservation diagram - into a script.  This is desirable so that the data in the table can vary per alternative without having to change the script.  A table can also be used to hold output from a script that can be passed on to another model or be used by the modeler to analyze results.

There are three types of tables that a modeler can create - a simple lookup table, a two-variable lookup table, and a report table.  A simple lookup table has one independent variable and one dependent variable.  An example of a simple lookup table could be a flow-stage rating curve.  A two-variable lookup table has two independent variables and one dependent variable.  An example of a two-variable lookup table could be a gate rating curve, where the dependent variable (outflow) depends on head and gate opening.  Both lookup tables can have one of the variables specified as seasonal data, which limits one of the independent variables' parameter type to Seasonal Date.  The report table has one independent variable and can have multiple dependent variables.  Report tables are useful for storing the value of lots of different variables that all depend on the same thing, like pool elevation.

Creating and Using Global Variables

Global Variables are created and configured through the use of a Global Variable Editor which can be accessed from the Edit menu in the Reservoir Network or Simulation Module.  When the Global Variable is first opened for a model where no Global Variables have been created, the window will appear empty as is shown in Figure: Global Variable Editor. To add a Global Variable, select New from the Global Variable tab. A new window will appear that will allow the user to select Time Series, Scalar, String or Table.

Time Series Global Variables

For a Time Series Global Variable, the user will need to select a Usage Type (Input or Output). Usage type determines whether the user will be inputting the data or whether ResSim will be outputting the data. If Input is selected, as seen in Figure: Input Time Series Global Variable in the Global Variable Editor, the user then only needs to select a Parameter Type and set a pathname in the Alternative Editor Time-Series tab. 

If Output is selected, as seen in Figure: Output Time Series Global Variable in the Global Variable Editor, the user will be prompted to choose a Parameter Type, Parameter Name, and Time Step.

Scalar Global Variables

For a Scalar Global Variable, user will need to select a Usage Type (Input or Output). Usage type determines whether the user will be inputting the data or whether ResSim will be outputting the data.

For an Input and Output Scalar Global Variable, the user will need to select a Data Type and a Parameter. The Data Type will determine what type of data can be entered within the Alternative Editor and what data will be Output. The Parameter is a Data Type descriptor.  Where the Input and Output Scalar Global Variables differ is in the additional constraints for the value of the global variable allowed for an Input.  For example, if the user enters a minimum value of 100 and then tries to set the value of the scalar variable to 50 in the alternative editor, they will receive an error because 50 is less than 100. The additional options are listed below but can also be seen in Figure: Input Scalar Global Variable in the Global Variable Editor.

• Setting a Minimum limit for the global variable
• Setting a Maximum limit for the global variable
• Creating a Selection List (i.e. a dropdown menu) that the user will select from when setting the value of the global variable in the Alternative Editor

An example of an Output Scalar Global Variable can be seen in Figure: Output Scalar Global Variable in the Global Variable Editor.

String Global Variables

For a String Global Variable, user will need to select Usage Type (Input or Output). Usage type determines whether the user will be inputting the data or whether ResSim will be outputting the data. 

For an Input String Global Variable, the user will need to select a Character Set. Depending on which Character Set is selected by the user (ASCII, Alphanumeric, or Alphabetic) restrictions will be applied on what data can be entered in the Alternative Editor.

In addition to the Character Set, the user may also set the following:

• Case Sensitive (Make Variable sensitive to character case)
• Invalid Characters 

An example of an Input String Global Variable can be seen in Figure: Input String Global Variable in the Global Variable Editor.

If the Selection List checkbox is selected, the parameters previously discussed disappear from the window and only a Selection List will be present as seen in Figure: Input String Global Variable using a Selection List in the Global Variable Editor. The user will need to add a list in this window and they will present as a drop down list in the Alternative Editor.

Table Global Variables

For Table Global Variables, user will need to select Usage Type (Input or Output). Usage type determines whether the user will be inputting the data or whether ResSim will be outputting the data. Whether the user selects Input or Output, the window will retain the same items.

This will prompt you to choose 2 Parameters which will determine how you set up the rest of the variable.

• Table Type
• Seasonal Data Check Box

From these two parameter types you get these permutations of Table Variables

• Simple Lookup Table
• Seasonal Simple Lookup Table
• Two Variable Lookup Table
• Seasonal Two Variable Lookup Table
• Report

Simple Lookup Table

Selection of a Simple Lookup Table will require the user to enter a Parameter Name and Parameter Type for the Independent and Dependent Variables. An example is shown in Figure: Simple Lookup Table in the Global Variable Editor.

Selection of Simple Lookup Table and checking the Seasonal Data box results in the Parameter Type of the Independent Variable changing to Seasonal Date and becoming uneditable. The user will still need to enter a Parameter name for the Independent Variable and a Parameter Name and Type for the Dependent Variable. An example is shown in Figure: Seasonal Simple Lookup Table in the Global Variable Editor.

Two-Variable Lookup Table

Selection of Two-Variable Lookup Table will require the user to enter Parameter Names and Parameter Types for the two Independent Variables and the Dependent Variables. An example is shown in Figure: Two-Variable Lookup Table in the Global Variable Editor.

Selection of Two-Variable Lookup Table and checking the Seasonal Data box results in the first Independent Variable's Parameter Type changing to Seasonal Date and becoming uneditable. The user will still need to enter a Parameter Name and Parameter Type for the second Independent Variable and the Dependent Variable. An example is shown in Figure: Seasonal Two-Variable Lookup Table in the Global Variable Editor.

Report Table

When Report Table Type is selected, the Seasonal Data check box greys out and the user is given the option to append additional dependent variables. An example is shows in Figure: Report Table in the Global Variable Editor.