Rules are user defined computation sequences which may be attached to certain variables within either the simulator or the water accounting module. When these calculators are invoked during begin time step, they return a number which sets the value of the variable to which they are attached.

Rules are designed to use Reverse Polish Notation (RPN). RPN is based on a stack of numbers, system variables and mathematical or logical operators. A stack is a first-in-last-out list. Values and operators are pushed into the stack. To perform the calculation, the items are popped off of the stack until it is empty. As each item is popped, it yields a value or performs an operation.

Perhaps the most familiar example of such a calculation sequence is a Hewlett-Packard calculator. Numbers are entered into the register and then operator keys ('+', '-', etc.) are pressed, the result of each operation appearing in the register. The only difference here is that the operators are also stored in the stack rather than yielding a value immediately.

The stack calculator in the first will set the flow through the "Roos Gen" generator. Since the head discharge table for this generator is calibrated in percentage opening, the calculator displays the two radio buttons at the top allowing the rule either to set flow or gate opening percentage. This calculator checks the value of the "Gen Calc" slot in the "Econ" table (the value of that slot also being set by a rule). If the value of that slot is zero, the rule returns the value "Off" (0), otherwise the value "Generate" (1).

The calculator window is divided into two panes with a button pad between them. The left pane contains a tree with all of the system variables listed. The right pane, initially empty, will contain a record of the variables, constants and functions that compose the rule. Clicking the Enter button moves a variable or constant onto the stack. Clicking the Remove button removes the top item from the stack.

• Numbers: To enter a number into the stack, click the mouse in the Register field and type in the number. If the number is to be a scalar multiplier or divisor, set the combo box to the right of the register to "No Units". If the value to be returned is to be in some engineering units (flow, volume, length, etc.) set the combo box to the right of the register to indicate the type of unit desired. Clicking the Enter button moves the value from the register to the stack and clears the register.

• Simulation Variables: All state variables from the model are accessible from the tree on the left side of the calculator dialog. Clicking the mouse on the desired variable and clicking the Enter button will move the desired state variable to the stack.

• Operators: The various allowed mathematical and relational operators are pushed into the stack simply by clicking the appropriate button on the central pad. With the exception of the IF operator explained below, all operators take the two stack entries immediately following as arguments. If one of the next two entries is itself an operator, that operator is evaluated and its result is the argument to the first operator.

• Undoing an entry: The Remove button removes the last item in the stack.

In addition to the normal arithmetic operators, rules may also use logical operators and IF statements. Logical operators like arithmetic operators, work on the following two terms in the stack. The value returned by a logical operator is either true or false ( 0 or 1 ).

The IF operator evaluates the next term in the stack (which is generally a logical operator or the result of a logical operation) and then evaluates either the first or second term after the test term, depending on the value of the test term. If the test term is true, the first item following in the stack is evaluated, otherwise the second.

The the rule in the figure above sets the release at Roosevelt to either 10,000 CFS or 50,000 CFS. The decision is based on the surface elevation of the downstream reservoir, Horse Mesa. If the surface elevation at Horse Mesa is above 2,000 Feet, Roosevelt's release is set to 10,000 CFS, otherwise it is set to 50,000 CFS.

Because rules can refer to other system variables, evaluation order becomes important. There are two different situations with respect to variable evaluation order:

• Water Handling Objects: When a rule referrs to a slot in a water handling object (reservoirs, confluences, diversions), the value returned to the rule by the slot is the slot's value at the end of the prior time step. Hence, if you want to make a rule to determine the release in a reservoir based on the inflow to that reservoir, release at time t is a function of inflow at time t - 1.

• Tables: Table objects are evaluated before any water objects during each time step. Within a table, slots are evaluated in order from top to bottom. That means that a table may be used to program an algorithm.

  From the modeler's perspective, when referring to the value of a table slot in a rule, there are two cases:

  • If the rule is being written from another slot within the same table, all slots higher in the list in that table are guaranteed to have been evaluated.

  • If the rule is attached to a slot on a water handling object, it is guaranteed that all table slots have already been evaluated before the water handling object will invoke any rules.