skip to main content
Initialization Rules Set
Initialization Rules are a set of RPL rules associated with the model which can be executed as part of run initialization to set up data for the run. Initialization Rules provide a complement to user inputs and execution of DMIs.
Unlike other rules which can only set series slots, initialization rules can be used to set Table Slots and Scalar Slots.
This section describes the applicability and use of Initialization Rules. See RPL User Interface for details on the user interface for Initialization Rules and other RPL sets.
When to Use Initialization Rules
Each method for providing data to a simulation is suited to different modeling scenarios. For situations in which there are a small number of inputs that don’t change frequently, interactive setting of input values is often the simplest approach. However, when this process would be time-consuming or error-prone, it is preferable to automate the setting of user inputs. Input DMIs provide a flexible way of accomplishing this by providing mechanisms for communication between RiverWare and external programs (usually databases). If there is computational logic involved in this process, e.g., if the data need to be massaged to remove outliers, then this logic must somehow be embedded in the external DMI program. On the other hand, using initialization rules to accomplish the same task allows this logic to be viewed and edited from within RiverWare, often improving the clarity and ease of maintenance of the model.
Initialization Rules also differ from DMIs in that in the context of a RBS simulation, they can be used to provide default values which the policy can then override. To illustrate a scenario in which this might be useful, consider a run in which some quantity is generally assumed to be zero, but which can take on non-zero values under some conditions. One strategy for modeling this situation is to set the relevant values to zero using low priority rules with execution constraints that cause them to execute only on the first timestep. Alternatively, Initialization Rules accomplish this same behavior with less user effort (no execution constraints are necessary) and with the additional advantage that these rules are organized separately from the policy (if there is one). In fact, most RBS rules which are constrained to execute only on the first timestep are likely to be more appropriately included with the Initialization Rules.
Another important distinction between Initialization Rules and policy (rules) is that the former are executed before data checking at the beginning of the run. Thus, Initialization Rules can be used to set values such as initial Storage or Pool Elevation on a reservoir, whereas RBS rules execute only after data checking and so could not be used to give these slots reasonable values. Further, unlike other rules which can only set series slots, initialization rules can be used to set table and scalar slots.
How to Use Initialization Rules
This topic describes how to use initialization rules.
How do I access the Initialization Rule Set?
From the workspace, use the Policy, then Initialization Rules RPL Set menu.
Where are they saved?
The set is saved in the model file. The Initialization Rules Set Editor dialog does have a File, then Save Initialization Rules Set As menu item to save the initialization rules to a file. A File, then Replace Initialization Rules Set from File menu item allows the initialization rules set to be replaced by the contents of a specified file. These menu items allow an initialization rules set to be moved between models via a file. However there is only a single instance of initialization rules in a model and this set is still saved and loaded with the model file. You can also use the File, then Clear Set to remove all items in the initialization set.
When are they executed?
The rules are executed during the initialization phase of Simulation and Rulebased simulation runs (including accounting) and Optimization runs. For Simulation/Rulebased, they are executed after values are cleared and inputs are registered but before beginning of run checks on all objects.
See Simulation Controller in Solution Approaches for details on the ordering for simulation.
See Initialization Rules in Optimization for information on Initialization Rules in Optimization.
In what order are they executed?
The Initialization Rules are executed in Index order based on the specified Agenda Order. To see the order, select View, then Show Advanced Properties.
What do Initialization Rules set?
Initialization rules can set series slots, table slots, scalar slots, and periodic slots.
• For series slots, the current timestep is the start timestep.
• For table slots, specify the rows and columns using labels or a zero-based index.
• For scalar slots, use the Object.ScalarSlot[ ] syntax on the left side of the assignment statement.
• For periodic slots, use the Object.PeriodicSlot[row, column] or Object.PeriodicSlot[row] syntax on the left side of an assignment statement.
The supported types for the row expression are DATETIME and NUMERIC. For a DATETIME value, an attempt is made to match the date with one of the rows of the periodic slot. The date must be partially specified and in the time, month, day, (and optional year) format, for example @ “23:00 July 1”.
Tip:  RPL uses 24:00 as the end of a day while irregular periodic slots use 0:00 on the start of the next day. For example 24:00 April 30 in RPL is the same as 0:00 May 1 on a periodic slot. When writing RPL logic continue, to use 24:00 notation but realize this will map to 0:00 on the slot.
If the row expression evaluates to a NUMERIC value, the value is truncated and used as a zero-based row index.
The column expression, if present, must have NUMERIC type. The value is truncated and used as a zero-based column index. If the column expression is absent, the first column is assumed (column index 0).
• The row and column numeric headings can also be set by initialization rules using the Set Row and Set Column statements. See Set Row and Set Column.
Do Initialization rules re-execute when dependent slots change?
No, initialization rules execute once and do not re-execute even if dependencies change.
Do Initialization Rules have Individual Priorities.
No, the Initialization rules are organized by Index as shown on the RPL set editor.
What Flag/Priority are the values given?
Series values set by Initialization Rules are given one of the following flags/priorities as configured through the Set Value Flag menu on each Initialization Rule:
• Rule (R). Set the value with the R flag. In RBS, all values set this way are given a very low priority (It is a very large number) and the letters IR are shown indicating the Initialization Rule priority. R flagged values set by Initialization rules can be overwritten like other R flagged values.
• DMI Input (Z). Set the value with the Z flag and give it a priority of zero (0) (in RBS). When simulating, this flag behaves identically to the INPUT (I) flag.
Note:  An Initialization Rule setting a value with the Z flag can overwrite an I or Z flagged value.
Note:  The values set by initialization rules are given the priority as described above. If these values are propagated or provide enough information for an object to dispatch, any subsequent values set will be given the controller priority, which would be zero (0) if they solve before any rules execute.
Note:  Table and Scalar slot values set by initialization rules are not give a priority or a flag. Choosing the R or Z flag from the menu shown above results in identical behavior for these types of slots.
Can I disable the Initialization Rules?
When the Initialization Rules set contains at least one rule, then the Run Control Dialog displays a check box labeled Execute Initialization Rules, which controls whether or not to execute the Initialization runs during the initialization phase of runs. Clear this check box to disable the Initialization Rules.
For an Optimization run, the toggle/flag is labeled Execute Initialization rules before Optimization Run.
Note, the toggles are separate for each controller. They can be on for one controller but off for another controller. See Set Init. Rules Exec. Flag in Automation Tools for a script action that sets these flags.
How do I know which Initialization rule set a slot value?
Tooltips on the series slot values display which Initialization Rule (or RBS rule or DMI) set that value. See the following figure. See Series Slots in User Interface for details on these tooltips.To open that rule, right-click and choose Open Init Rule #.
How do I debug Initialization Rules?
The RPL debugger can be used with Initialization Rules. Also, the following diagnostic categories in the Rulebased Simulation and Simulation settings dialog control diagnostics for the Initialization Rules:
• Init. Rules Print Statements
• Init. Rules Rule Execution
• Init. Rules Function Execution
See Types of RPL Debugging and Analysis in Debugging and Analysis for details on debugging and analysis of RPL sets.
Revised: 01/05/2024