How the Accounting System Solves
The accounting system does not dispatch in the same way that the physical water network simulation is dispatched, but there are some similarities. Account solution is triggered by the assignment of a value to a slot on the account. Assignment to account slots occurs in one of six ways: by user input, by a rule, by propagation through a supply, account solution, account-level method, and by an object-level accounting method on the object that references physical water quantities to introduce water into the accounting system (paper water). Table 1.1 provides details on each type of assignment.
Accounts solve whenever sufficient known slot values are present to run a solution method. This is analogous to dispatching in the simulation network; however, in the case of the accounting system, this means that accounts may solve when a user edits the account values through the user interface, a rule sets a value, or a method sets a value. Therefore, a run is not required to make a single account solve.
Each time an account slot is given a value (during resetting of user input, execution of object-level methods, rule execution, or during account solution), the account holding the slot is notified, and performs its own checks for over- and under-determination, and possibly solves at one or more timesteps. Some accounts solve into the future under some circumstances, even though the controller might be at a different timestep.
Outside of a run, accounts solve for as many timesteps as there is the required known data. This means that the account solution behaves similarly to a spreadsheet solution. If the user inputs an Outflow for each timestep in the accounting period for a storage object and all of the inflows, slot inflow and Gain Loss are known, then the account will solve for Storage at each timestep. This action is performed when the user hits the enter button. If the user then changes an Outflow value at the start of the accounting period, then the storage for the entire period will change because the solution equation for the storage account depends on the previous timestep’s Storage. By changing one Outflow, the Storage for the whole period is affected.
In a run, the solution is similar, but accounts will only solve into the future one timestep, even if enough information is given for the accounting system to solve for the entire run. For example, if Gain Loss and Slot Inflow of a storage account are known for an entire month starting on the 1st of the month, the storage will be solved for the entire month during that first timestep. During the course of the run, a transfer on the 10th of the month will reset the storage on the 10th of the month, and the 11th of the month, but won’t reset storage on the 12th or any subsequent date.
There are three controllers that allow accounting: Post-simulation Accounting, Inline Simulation and Accounting, and Inline Rulebased Simulation and Accounting. These three controllers and their solution steps during a run are described in the following subsections.
Post-simulation Accounting
The simulation must be run under the Simulation controller, then the post-simulation accounting process can be run under the Post-simulation Accounting controller. The user must manually switch between controllers for each run. Accounts solve when they have the required knowns and resolve when a value in the solution equation changes.
Simulation Steps
See Simulation Controller in Solution Approaches for a description of the process followed by the Simulation controller.
Accounting Steps
The Post-simulation Accounting controller follows the procedure outlined below in the process of a run:
1. Initialize Accounting Run
– Clear Iteration count
– Clear Account States; that is, Output values and Output flags
– Set Accounting User Inputs
2. Accounting Beginning of Run
– Execute Beginning of Run Account Level Methods for all objects.
– Execute the object-level accounting methods that are set to execute at Beg. of Run.
3. For each timestep,
– Execute the object-level accounting methods that are set to execute at Beg. of Timestep and Beg. of Timestep Once.
– Execute the object-level accounting methods that are set to execute After Simulation.
– If dependent accounting slot have changed, re-execute as necessary object-level accounting methods that are set to execute at Beg. of Timestep or After Simulation.
Inline Simulation and Accounting
For each timestep, the physical simulation and accounting method execution are intermixed. Accounts solve when they have the required knowns and resolve when a value in the solution equation changes.
Simulation Steps
The simulation controller follows the procedure outlined below in the course of a run:
1. Initialization Simulation Run
– Clear all output and values from previous runs for all timesteps in all series slots.
– Set user inputs.
– Propagate user inputs across links.
– Determine first dispatch timestep. See Initialization in Solution Approaches for additional information.
2. Initialize Accounting Run
– Clear Iteration count
– Clear Account States; that is, Outputs and Output flags
– Set Accounting User Inputs
3. Execute rules in the Initialization Rules RPL set. See Initialization Rules Set in RiverWare Policy Language (RPL) for additional information.
4. Simulation Beginning of Run
– Execute Beginning of Run methods for all objects.
– Evaluate Beginning of Run expression slots for all timesteps.
5. Accounting Beginning of Run
– Execute Beginning of Run Account Level Methods for all objects.
– Execute the object-level accounting methods that are set to execute at Beg. of Run.
6. For each timestep:
– Set the controller clock to the timestep time.
– Execute the object-level accounting methods that are set to execute at Beg. of Timestep and Beg. of Timestep Once.
– Execute Beginning of Timestep methods for all objects.
– Evaluate Beginning of timestep, current timestep only expression slots
– Dispatch objects until the queue is empty, simulating the effects of the user inputs and default values.
– Execute End of Timestep methods on all objects.
– Execute the object-level accounting methods that are set to execute After Simulation.
– For OLAMs set to execute After Simulation or Beg. of Timestep, re-execute if dependent slots have changed.
– Evaluate end of timestep, current timestep only Expression slots
7. Execute End of Run Simulation methods on all objects.
8. Evaluate End of Run expression slots.
Inline Rulebased Simulation and Accounting
For each timestep, the rulebased simulation is run where slots are set by rules, the simulation objects dispatch, and user-defined accounting methods execute. Remember that accounts solve when they have the required knowns and re-solve when a value in the solution equation changes. This can happen at any time throughout the course of the run or even outside of the run.
This section describes the inline rulebased simulation and accounting steps in more detail. First, the run steps are presented in paragraph format, then they are presented in bullet format. See Rulebased Simulation in Solution Approaches for details about rulebased simulation.
Note: Execution of rules and dispatching (simulation) of objects are intermixed and may be mutually dependent.
Rulebased Simulation Process Overview
At each timestep, the controller cycles the following process.
1. Processing the object dispatch queue. Objects check their dispatch conditions and may try to dispatch (or re-dispatch) after a dispatch slot on the object changes value. An object maintains a list of its dispatch slots and dispatching only occurs if it has sufficient known values.
2. Processing the accounting queue. Object-level accounting methods with the execution time of Beg. of Timestep can have simulation slot dependencies so that when the dependent simulation slot changes, the method is placed onto the accounting queue for processing. The accounting queue is processed in a first in, first out order.
3. Executing rules from the agenda one at a time. When a rule is successful, all its slot assignments are made. If it is not successful, none of its assignments are made; that is, never are some, but not all of the assignments made. When the rule succeeds, the slot cell whose value was changed is given the priority of the rule and the “R” flag. These values show up in the rules analysis dialogs. Each rule maintains a list of the slots on which the outcome of the rule is dependent, namely those slots that were read during the rule execution. A rule will re-execute after one or more of its dependency slots changes value. Thus, objects that are dispatching can cause rules to re-execute by changing the values of slots upon which the rules depend, while rules that change dispatch slot values can cause simulation objects to dispatch. In the accounting system, a rule can change an account slot's value, which may cause the account to solve and may propagate changes throughout the accounting system. This can happen during a rule execution, but not during an object dispatch. A change in a simulation slot can also cause an object-level accounting method to go onto the accounting queue if the slot is a dependent simulation slot of the method,. This can occur during rule execution or during an object dispatch,
4. At the start of the timestep (after beginning of timestep behavior has occurred where object-level accounting methods may be executed), 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. Then the accounting queue (Step 2.) is processed to execute any object-level accounting methods that have come onto the queue.
5. Once this queue is empty, the rules controller moves to Step 3. 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 or object-level accounting methods on the accounting queue. After a rule succeeds and sets a value, the controller returns to Step 1. and dispatches all objects on the dispatch queue, and then proceeds to Step 2., where it executes all object-level accounting methods on the accounting queue.
6. When the dispatch and accounting queues are again empty, the controller returns to Step 3. and executes the next rule on its agenda. Once a rule succeeds, it returns to Step 1. and processes the dispatch queue and then the accounting queue. It continues cycling until the dispatch and accounting queues and the rules agenda are empty.
7. When all simulation dispatching is complete and the rules agenda is empty, object-level accounting methods may execute under the accounting controller and then the simulation moves to the next timestep.
Rulebased Simulation Steps
The rulebased simulation controller follows the procedure outlined below:
1. Initialization Rulebased Simulation Beginning of Run
– Clear all output and values set by rules from previous runs for all timesteps in all series slots.
– Set the controller priority to 0.
– Set user inputs.
– Propagate user inputs across links.
2. Initialize Accounting Run
– Clear Iteration count
– Clear Account States; that is, Outputs and Output flags
– Set Accounting User Inputs
3. Execute rules in the Initialization Rules RPL set. See Initialization Rules Set in RiverWare Policy Language (RPL) for details.
4. Rulebased Simulation Beginning of Run
– Execute Beginning of Run methods for all objects.
– Evaluate Beginning of Run expression slots for all timesteps.
5. Accounting Beginning of Run
– Execute Beginning of Run Account Level Methods for all objects.
– Execute the object-level accounting methods that are set to execute at Beg. of Run.
6. For each timestep:
a. Set the controller clock to the timestep time.
b. Execute the object-level accounting methods that are set to execute at Beg. of Timestep and Beg. of Timestep Once.
c. Set controller priority to 0.
d. Execute Beginning of Timestep methods for all objects.
e. Evaluate expression slots that have evaluate-at-beginning-of-timestep selected
f. Put all rules on the agenda (in priority order - whether 3,2,1 or 1,2,3 is user-selectable)
g. Do the following processes until the dispatch queue, the accounting queue, and the rules agenda are empty.
• Process 1 - Process the Dispatch Queue. Dispatch objects (as in basic Simulation) until the queue is empty, simulating the effects of any user inputs and default values and any recent changes to slots by rules. For each slot changed by this dispatch:
1. Put all rules that depend on the changed slot on the agenda, if it's not already there.
2. If the slot is a dispatch slot, check dispatch conditions and if necessary put the object containing the slot on the simulation dispatch queue.
3. Put all Object Accounting Methods with execution time of Beg. of Timestep that depend on the slot on the accounting queue.
4. If the slot is an accounting slot, notify the account that it may need to solve.
5. Once the Dispatch Queue is empty, move on to process 2.
• Process 2 - Process the Accounting Queue. Execute any object-level accounting methods that have come onto the accounting queue. For each slot changed as a result of method execution:
1. If the slot is an accounting slot, notify the account that it may need to solve.
2. If the slot is an accounting slot, put all object-level accounting methods that have a dependency of this accounting slot onto the accounting queue for execution if the method’s execution time is also Beg. of Timestep.
3. Once the Accounting Queue is empty, move on to process 3.
• Process 3 - Execute a Rule on the agenda. Set the controller priority to the priority of the next rule on the agenda (either in order 3,2,1 or 1,2,3 based on user-selection), and fire this rule. If not successful, continue firing one rule at a time until a rule is successful and at least one slot is set in the model. Each rule is removed from the agenda after it fires. Once a rule is successful:
1. Apply the slot changes, giving the changed slot cell the priority of the controller (that is, the last rule that fired)
2. Add to this rule’s dependency’s list each slot that was read by this rule.
3. For each slot set by this rule, put all rules that depend on the changed slot on the agenda if the rule is not already there.
4. For each slot changed by this rule, if the slot is a dispatch slot, check dispatch conditions and if necessary, place the object containing the slot on the simulation dispatch queue.
5. For each slot changed by this rule, if the slot is an accounting slot, notify the account that it may need to solve.
6. For each slot changed by this rule, if the slot is a dependent simulation slot for an object-level accounting method with an execution time of Beg. of Timestep, add the method to the accounting queue.
h. Return to Process 1 and repeat until the Agenda and the Queues are empty.
i. Set controller priority to zero, and execute End of Timestep methods on all objects.
j. Execute the object-level accounting methods that are set to execute After Simulation.
k. If dependent accounting slot have changed, re-execute as necessary object-level accounting methods that are set to execute at Beg. of Timestep or After Simulation.
l. Evaluate end of timestep, current timestep only Expression slots
7. If the number of run cycles performed is less than the number of run cycles specified, return to Step 6. and loop through each timestep again. See Run Cycles in Solution Approaches for additional information.
8. Execute End of Run Simulation methods on all objects.
9. Evaluate End of run expression slots.
Revised: 07/09/2023