Like State Variables, each new Scripted Rule will be created with a template. "Figure: The Scripted Rule Template" displays the Scripted Rule template. This template has some very important lines of code as well as several comment statements which are marked with the number sign (#).

Figure: The Scripted Rule Template

The template basically gives you instructions on three key elements that you must provide in your script:

  • The two function statements for the initRuleScript and runRuleScript functions. You should use these statements as-is, do not edit them.
  • The opValue object, its init (or set) method, and the constants that represent the available limit types.
  • The return statements that will cause ResSim to correctly receive the result of your script's functions and utilize that information within the release decision logic.

Looking at the template in more detail, you will notice that it starts with some import statements. Import statements are needed to "teach" your script what it needs to know about the java objects your script will be using. The three import statements in the template are required for your scripted rule to function properly. It is recommended that you add any additional import statements that your script may need below these lines.

Below the imports are the two function definitions mentioned above. Each function's def statement is preceded by several comment lines that describe the function and its arguments. Since the two functions are called by ResSim during the Regulated compute, the arguments are objects that are passed into your script from your model. A more comprehensive description follows:

initRuleScript—this function is where you should put the setup code for your rule. This function is called by the rule object only once, at the start of the regulated compute loop. Use the function definition statement as-is, do not edit it. It is the content of the function that you are expected to edit. The function must return a value of Constants.TRUE (to indicate success) or Constants.FALSE (to indicate failure). It is up to you to determine if your script requires special logic that might cause it to return FALSE. The return value of the initRuleScript function should be True for successful and False for unsuccessful. If this function returns false, the ResSim compute will be aborted.

runRuleScript—this is the "main" function of the script. This function is called by the rule's evaluate method and is called at least once per timestep. Use the function definition statement as-is, do not edit it. It is the content of the function that you are expected to edit. This is where you should put the code that calculates the desired release limit of your rule. The return value of the runRuleScript function is an OpValue object. In this object, you are expected to store the value of the desired release limit that you calculated and the limit type.

The function arguments—the two default functions of your scripted rule receive some variables (arguments) that are provided by ResSim so that your function can access model data needed to compute the value of the rule's desired release limit. The three variables that may be provided are described below. Both functions receive the first two variables. Only the runRuleScript function receives the third variable.

currentVariable—is a reference to the current state variable object itself. currentVariable is conceptually equivalent to the this keyword in Java or the self keyword in Python.

network—is a reference to the object that holds the reservoir network. It can be used to access to all the elements of your network and their model variables such as pool elevations, inflow, diversions, etc. It can also be used to access the current alternative and its properties.

currentRuntimestep—is a reference to the object that holds the timestep being evaluated. The actual date & time of the timestep, as well as the sequence number of the timestep and the run time window are accessed through this object. This object is used, among other things, to determine where (or is that when) to store the computed value of the state variable.

The opValue object—this object is used to carry each rule's desired release limit value and the limit type back to ResSim (through the return statement) for use in determining the allowable release range (see the introduction to "Reservoir Operations - The Rules" for details on the release range). As described in the template, the limit types are:

  • OpRule.RULETYPE_MAX—maximum flow
  • OpRule.RULETYPE_MIN—minimum flow
  • OpRule.RULETYPE_SPEC—specified flow

The template also shows how to create an OpValue object and how to initialize it:

# create new Operation Value (OpValue) to return
opValue = OpValue()

# set type and value for OpValue
opValue.init(OpRule.RULETYPE_MAX, 1000)

Remember, for these lines to work, the imports at the top of the template must be included in your script.