Rulebased simulation is an extension of the RiverWare basic Simulation feature, in which some of the data to solve an underdetermined model is provided by a set of user-defined rules. Rule execution alternates with dispatching to simulate the effects of the rules in the model.

Rulebased Simulation can only be understood once the fundamentals of basic Simulation have been mastered. This section assumes that you have a familiarity with simulation; see “Simulation” for details. However, we will briefly review some key concepts to ensure that everyone’s knowledge is current.

Rulebased Simulation is a variation of RiverWare basic Simulation, in which an underdetermined model is provided additional information from user-specified rules that represent the operating policy of the basin. A Rulebased Simulation model does not contain enough inputs for all objects to solve. Instead, it relies on the rules to provide additional information needed to fully solve the model. Rules provide this information by setting slot values in the model. The information provided by the rules, together with the input data, results in an exactly specified model.

The rules are logical statements formulated by the modeler and written within RiverWare, in a special language which is interpreted at runtime. Thus, the rules are data which can be saved and modified without having to recompile a program.

Rulebased Simulation works by alternating between executing rules and dispatching objects on the queue. The rules set values in slots. As a result of these values, objects may have enough information to dispatch. The ensuing dispatching simulates the effects of the rules in the model.

The Rulebased Simulation controller is available in RiverWare as an alternative controller to the Simulation controller. The Rulebased Simulation controller uses the same physical process algorithms as the Simulation controller, so the same user methods and slots are available regardless of which controller is active. You do not need to modify a model built for basic Simulation to run it under the Rulebased Simulation controller, other than setting slots to “output” which will be set by the rules. Data specific to User Methods do not need to change. This allows the same model to be used for what-if scenario runs using Simulation and for policy-driven model runs with Rulebased Simulation.

A single rule consists of one or more logical statements which assign values to one or more slots in the model. The rule is written in a special language, the RiverWare Policy Language (RPL). The rule’s logic may reference the current state of the model—determined from the values in slots—to decide if, and to what value, slots are assigned.

Rules are designed and constructed by modelers to mimic policy and decisions which would normally be implemented in scheduling river and reservoir operations. Ideally, each rule represents a specific operating policy. The set of rules represents the entire operating policy for the basin. In order to resolve conflicting policy in rules, the modeler gives each rule a unique priority relative to the other rules. Higher priority is indicated by a smaller number; i.e., priority #1 is higher than priority #2.

A simple guide curve rule for a reservoir is shown below. This rule looks at the Spill slot on the Hoover Dam object at the current timestep. If there is no spill, the rule reads the Guide Curve Elevation from a data slot and sets Hoover Dam’s Pool Elevation equal to it. If, however, Hoover Dam is spilling, then the rule has no effect.

The format of the rule may look unusual if you are accustomed to programming in languages such as FORTRAN and C++. In those languages, it is normal to put the assignment statement within the logic (inside the THEN clause of the IF statement). In RPL, all slot value assignments are made at the top level of the rule. The slot being assigned a value appears on the left-hand side (LHS). The right-hand side (RHS) is a logical construct which evaluates to a single value or to nothing.

When a rule executes, or fires, the rule is interpreted and logic of the rule is executed. Firing a rule does not imply that a slot value necessarily will be set. In the example above, if HooverDam.Spill is zero, the RHS evaluates to the Guide Curve Elevation. If, however, the spill is greater than zero, the RHS does not result in a value, and no assignment is made. It is also possible that the HooverDam.Spill slot does not have a value, in which case there is not enough information for the RHS to result in a value.

Firing of a rule only means that the rule’s logical expressions will be evaluated and that the evaluation may result in a slot value being set. There are three possible outcomes when a rule fires.

A rule’s dependencies are all the slots that the rule’s logic referenced the last time the rule fired during the current timestep. These are the slots on which the rule’s outcome depends. As a rule’s logic is executed, the rule processor keeps track of all slots referenced in the logic. In practice, any slot whose value at the current timestep is used during a rule firing is automatically added to the dependency list for that rule.

If any of the values of the dependencies subsequently change during the rest of the timestep, the rule must refire. When it refires, the RHS may evaluate to a different value — resulting in a different slot assignments—and perhaps a different outcome, than during its previous firing.

The dependency list is generated anew each time a rule fires.

The agenda is a list of rules eligible to be fired. The user can select whether the list is in order of priority from the highest eligible rule at the top to the lowest eligible rule at the bottom or vice versa.

At the start of each timestep, all rules in the ruleset are added to the agenda. This ensures that each rule will be fired at least once before the end of the timestep. When the rules processor is ready to execute a rule, it fires either the highest or lowest priority rule on the agenda (depending on the selection the user has made). After a rule fires, it is removed from the agenda. Whenever any of its dependencies gets a new value, the rule is added back onto the agenda in its appropriate place according to priority. Therefore, rules always fire in the priority order specified by the user.

The rulebased simulation controller orchestrates the alternation between execution of rules and solving of the simulation during a rulebased simulation run. It manages the dispatching of objects on the dispatch queue, just as the simulation controller does. When no objects can dispatch, the controller invokes the rule processor. The rule processor fires rules on the agenda, in the priority order specified by the user, until a rule is successful. Then, the controller again processes the dispatch queue.

An additional function of the rulebased simulation controller is to track the controller priority when objects are dispatching. The purpose of the controller priority is to track the priority of the effects of rules as they are simulated in the model.

The controller priority during object dispatching reflects the priority of the information driving the dispatching. During Initialization, Beginning of Run, End of Run and each Beginning and End of Timestep, the controller priority is set to 0. During Initialization, user inputs are “set” in the slots. During Beginning of Run and Beginning of Timestep, default values are set where user input has deliberately been left out. Any slots set during these times are considered in rulebased simulation as if they had been directly input by the user. The controller priority of 0 remains in effect during the dispatching which occurs immediately after Beginning of Timestep. Since no rules have fired yet, all of these dispatches result from user input.

After a rule successfully fires and sets one or more slot values, the controller priority is set to the priority of the successful rule. As a result of these slot values, one or more objects may be ready to dispatch. Since the impending dispatch and any subsequent dispatches are a direct result of the rule’s slot assignment, these calculations are performed at the priority of the rule.

The rulebased simulation controller behaves similarly to the simulation controller. (See “Simulation” for details of the simulation controller.) During the Initialization, Beginning of Run and Beginning of Timestep method executions, the rulebased simulation controller behaves much like the basic simulation controller: outputs are cleared, inputs set, links are propagated, expression slots are evaluated, and objects are initialized.

This section describes the timestep specific inline rulebased simulation steps in more detail. First, the steps are presented in paragraph format, then they are presented in bullet format. During the timestep-specific inner loop of the rulebased simulation controller, control alternates between dispatching objects and the rule processor as described in the following steps:

At the start of the timestep (after beginning of timestep behavior has occurred), the dispatch queue (step 1) is fully processed until empty. This simulates the effects of user inputs. In this processing of the dispatch queue, objects may dispatch one or more times or may not dispatch at all depending on the dispatch slots that are set or changed throughout the course of the dispatching.

Once the queue is empty, the rules controller moves to the second step and starts with the full set of enabled rules on its “agenda” in priority order. This ensures that each enabled rule gets at least one chance to execute. The controller tries to execute the first rule on the agenda, in user specified order, at which time the controller removes the rule from its agenda. A successful rule may put objects on the simulation dispatch queue. After a rule succeeds and sets a value, the controller returns to step 1 and dispatches all objects on the queue.

When the dispatch queue is again empty, the controller returns to Step 2. and executes the next rule on its agenda. Once a rule succeeds, it returns to step one and processes the dispatch queue. It continues alternating until both the dispatch queue and the rules agenda are empty.

The rulebased simulation controller follows the procedure outlined below:

In RiverWare Simulation, solutions are possible forward and backwards in time. For example, reaches can solve upstream and backwards in time for some routing methods, and target operations on reservoirs solve previous timestep operations to meet a current target. In Rulebased Simulation, however, the rules should set only current values; i.e., values at the current controller timestep. The simulation should move forward in time, completely solving each timestep, then moving forward to the next.

Rulebased simulations can cycle through the timesteps multiple times; each pass through the run timesteps is referred to as a Run Cycle. Traditionally (and by default) rulebased simulations cycle through the timesteps a single time, i.e., the default number of Run Cycles is 1. You may adjust this value upwards in the Rulebased Simulation Run Parameters dialog, which is accessed from the Run Control dialog's View menu. See “Rulebased Simulation Run Parameters” in User Interface for details.

To illustrate one use of this feature, consider a model consisting of two subbasins, where the policy of the lower basin requires knowledge of the upstream basin’s output for all timestep. One way to model this situation is to configure the simulation to cycle through the timesteps twice, solving for the upstream basin on the first run cycle and the downstream basin on the second. To do this, you would add execution constraints to the rules governing the upper basin which constrain them to execute only if the current run cycle is 1, and, similarly, the remaining rules that apply to the lower basin would be constrained to execute only on the second cycle. Execution constraints and RPL expressions in general can access the current run cycle using the predefined function GetRunCycleIndex. See “GetRunCycleIndex” in RiverWare Policy Language (RPL) for details.

Together these features allow you to control which aspects of the policy apply to which portion of the run, which in turn allows parts of the model to solve fully before other parts—rules have access to slot values computed at all timesteps on previous run cycles.

More complex logic than that used in the previous example could allow rules/objects to solve on multiple cycles. Much like the way in which iterative MRM allows logic to control the number of runs, user logic could control the number of cycles. To do so, you would set the Number of Run Cycles parameter to a larger number, and then use logic and the STOP RUN statement to stop the run when the simulation goal had been achieved.Why might this feature by used instead of Iterative MRM? Run cycles are executed within a single run, you can run a model that is using multiple run cycles within a concurrent MRM to evaluate different hydrologies or policies.

When the number of Run Cycles to be greater than 1, the run control has additional controls for pausing as shown in Figure 2.1. Select both the timestep and the Run Cycle in which to pause. Also, notice that the Run Status at the bottom of the figure also shows the Run Cycle number.

Whenever a slot value is set in rulebased simulation, a priority is assigned to the value. This is termed the slot priority and can be displayed on the slot using the View, then Show Priorities menu. It indicates the priority associated with a specific value in a single timestep of a slot. The slot priority is the controller priority in effect when the slot is set. Thus, slots that are set during simulation have the priority of the last rule that succeeded. Slots that are set by rules have the priority of the rule that set them.

In simulating the effects of a rule, the slot priorities propagate the rule priority along with the values which result from the rule’s slot assignment. Slot priorities are used to determine how an object will solve and whether or not the slot value may be overwritten by values at other priorities.

Slots which have an R flag are more important than slots at the same priority without an R flag. This difference is discussed in more detail below.

When a rule sets a value on a slot which is part of an equivalent slot pair, it is essentially determining the value of the equivalent slot as well. For this reason, both slots are assigned the priority of the rule. The slot whose value is being set is assigned an R flag, but the equivalent slot is not. This is because the value of the equivalent slot will not be known until it is solved for during the dispatch. The equivalent slot’s value was not truly set, so it is not assigned an R flag.

When dispatching, if a value is set on a slot which is part of an equivalent slot pair, the slot is assigned the priority of the equivalent slot, regardless of the controller priority. For example, if Pool Elevation is a user input it will have a 0 priority and an I flag. If rule 1 sets Inflow, then the object can dispatch given Inflow (at a priority of 1) and Pool Elevation (at a priority of 0). All slots set as a result of dispatching will receive a priority of 1 because that is the controller priority (the priority of the last rule that successfully fired). However, the Storage slot will not receive a priority of 1. It will receive a priority of 0 because that is the priority of the Pool Elevation slot, which is the equivalent slot.

To summarize, slot priorities and flags are assigned to slot values as follows:

In simulation, if a slot is reset, the value must come from the same source as the previous value. (The three possible sources are user input, link propagation, or the object’s dispatch method.) This is required in simulation because when objects resolve due to inter-object iterations, they must solve for the same set of known and unknowns each time. Violation results in an over-determination error.

In rulebased simulation, however, the objects need the flexibility to solve with different sets of inputs and outputs in response to new values which may be set by the rules. To accomplish this, slot values in rulebased simulation may be reset from any source.

There are, however, restrictions on the setting of a slot value in rulebased simulation. The criteria used to determine whether a slot assignment can be made are as follows:

Table 2.1 summarizes this logic, and Table 2.2 provides examples.

In addition to the Series Slot logic described above, Multi Slots have special logic for handling the solution of their subslots. Remember that a multislot adds a subslot for each link and that the multislot is always the total of the subslots, as in the diagram below. A single unknown, either the multislot or one of the subslots, may be solved for from the known information.

In the sample multislot in Table 2.3, the Total column could be solved for if both of the Link columns have values. Likewise, either of the Link columns could be solved for if the Total column and the other Link column have values.

When there is only one unknown among the multislot and the subslots, it is solved. Once all subslots and the multislot are known and one of them gets a new value, a decision must be made as to which values to retain and what value to recalculate. That decision is based on which slot was solved for the last time and the priorities of each subslot:

In all cases where a subslot is solved for, this subslot is assigned the same priority and R flag status as the subslot which originally received a new value.

Priorities and R flags are maintained across links. Whenever a value is set on one end of a linked slot, the value, priority, and R flag (if present) are assigned to the slot on the other side of the link. Likewise, multislots propagate their priorities and R flags across their links when they solve.

Unlike basic simulation, an object in rulebased simulation may dispatch with different dispatch methods in a single timestep. The complication for the objects is determining which dispatch method to use whenever it gets a new slot value. Until an object dispatches for the first time during a timestep, it checks its knowns and unknowns against the dispatch conditions of its dispatch methods. This is the same process used in basic simulation. When the required knowns and unknowns are met, the object dispatches for the first time.

After the object has dispatched once at a given timestep, all of its dispatch slots should be known. If a new value is later set on a dispatch slot, the object must redispatch. But checking required knowns and unknowns is no longer a useful mechanism for determining the method with which to redispatch. In basic simulation, because slot values at a timestep are always set from the same source, the object simply redispatches with the same dispatch method used in the first dispatch.

In rulebased simulation, however, values may be set from different sources. The priorities of the dispatching slots must be used to determine the dispatch method. The dispatch method used for redispatches is the one who’s required knowns have the highest priority slot values.

The slots in a dispatch method’s required knowns list are divided into potential governing slots and non-governing slots. Potential governing slots may determine with which dispatch method an object can solve. Non-governing slots are simply a requirement for every dispatch method. For example: Inflow and Outflow are potential governing slots, Diversion is not. Let’s explore the reasons why. A river Reach object may solve upstream or downstream, depending on whether Inflow or Outflow are known. Inflow and Outflow are potential governing slots. If the object solves upstream in response to a known Outflow, the governing slot is Outflow. If, however, the object solves downstream in response to a known Inflow, the governing slot is Inflow. While both Inflow and Outflow are potential governing slots in this scenario, only one can be the actual governing slot. Diversion is a non-governing slot. A Storage Reservoir object may solve for its Inflow, Outflow, Storage, or Pool Elevation. In all cases, Diversion must be known for the Reservoir to mass balance. If Diversion is known, this only means that the Reservoir can dispatch, it tells us nothing about which of the dispatch methods the object can solve with. In general, the Governing slots are the slots which uniquely determine the dispatch method an object can solve with. The governing slots determine in which “direction” an object solves.

The potential governing slots for each object are listed below. All other dispatch slots are considered non-governing slots.

Once the knowns and unknowns of an object have uniquely identified a dispatch method, the actual governing slots can be identified. The actual governing slot(s) is (are) the slots which are in the potential governing slots list and are a required known for the dispatch method. The actual governing slot(s) may be one or two, depending on the object. For Reservoir objects, there are two governing slots, selected from the list of potential governing slots. For Reach objects, there can be only one governing slot.

The determination of a dispatch method for redispatching is based on the priorities of the slots. Once the object has dispatched once, all dispatch slots will be known, so checking knowns and unknowns is ineffectual. To determine the dispatch method, it is necessary to construct an alternate known slot list using the highest priority slots. RiverWare begins with an empty known slot list, then adds slots in priority order until a set of dispatch conditions is met. Since the non-governing slots are all known and they do not influence the choice of which dispatch method to solve, there is no point in prioritizing them; all non-governing slots are added to this list first. Then, the governing slots are added to the known list in priority order to determine the dispatch method.

The algorithm to determine the correct dispatch method for redispatching is as follows.

This algorithm always results in the identification of a dispatch method or an error and terminated run.