Assurance Rules

Owned by Nicole Norris (Deactivated)
Last updated: 17 Apr 2024 by Jin Wang

Source has a set of Assurance Rules that provide optional checks of models, accessible via Edit » Scenario Options. Assurance Rules define and detect unacceptable states in the model, increasing the confidence that the user can have in the model and the output data. Users can customize Assurance Rules in Source by choosing the severity of the notification if an Assurance Rule is not met by the model. Further customization is possible by creation of plugins that define custom Assurance Rule(s). Functions with Custom Logs may also be used for validation and logging at custom notification levels.

Figure 1. Scenario Options, Assurance Rules

The notification level of each rule can be set using the drop down menu next to each rule. The outcome of each notification level is summarised in Table 1. 

Performance Improvement

Performance can be improved by setting the notification level of an assurance rule to Off, then Source will not check that rule when the model is run. Alternatively, if Enabled is toggled off, all Assurance Rules are set to Off, and are not checked.

Care should be taken when turning off any or all assurance rules. Turning them off is not recommended during model building, but would be useful for calibrating or running replicates. 

Table 1. Assurance Rules, Notification levels
Notification levelSymbolOutcome
Off–The rule is not checked. This will improve performance.
Info

Message logged in the Log Reporter for each instance in which the rule is not met.

Warning

Message logged in the Log Reporter for each instance in which the rule is not met.
Error

Message logged in the Log Reporter for each instance in which the rule is not met.
Fatal

If the rule is not met, the model will stop running.

Assurance Rules and their associated notification levels apply to all model elements in the Scenario. If custom validation and/or differing notification levels are required on a per model basis, then Functions with Custom Logs may be used in addition to Assurance Rules.

Each Assurance Rule is described in Table 2.

Table 2. Assurance rule definitions
Assurance Rule CategoryDefinition
Advanced use

All file data sources used in the current input set are checked to ensure they each have a time series assigned to that input set.

Nodes are checked to ensure only confluences have multiple upstream links.

Continuous AccountingAllocation priorities are checked to ensure they match the priorities of the account types.

Data Sources

The rules to check the source access, usage, loading, and validation for Data Sources:

  • Data Sources result units must be commensurate with their usages. Such as a dataset in Data Sources with no unit selected (None) is assigned as the inflow (ML/d) at an inflow node. The rule will be triggered when the scenario is running.
  • Data Sources with By Position match method need to take care if the underlying CSV columns have been repositioned. Such as, the dataset in Data Sources uses the By Position match method and its first column is called X, but the name in the source file (e.g. a CSV file) is changed to Y. The rule will be triggered when the scenario is running.
  • Scenario Data Sources should be connected. Such as the rule is triggered during data reloading if the data source file was removed.
  • Scenario Data Sources with reload on run on should be run first.
  • Validate errors on reload on run. Such as the previous inflow unit is ML/d used for an inflow node, but the reloaded inflow data has a self-defined unit hour, this rule will be triggered.
Functions
Function result units must be commensurate with their usages:

All functions that are used as an input for a model element (eg. nodes, links) are checked to ensure that the result units configured for the function in Function Editor are commensurate with the usage units. For example, a function used as input for an Inflow node, should be set in Function Editor. Note that for the Boolean function and some conditional functions, such as the condition function in Resource Assessment Trigger, Result Units is not applicable and can use the option of no unit selected.

Modelled variable units must be commensurate with their assigned model property:

All modelled variables that are used by a function used in the scenario are checked to ensure that the units configured for the modelled variable in Function Editor are commensurate with the units for the model element (eg. nodes, links) property.

A Time of Evaluation must be set for Functions (unless constant), and variables set to Specify ToE

All functions and variables, which are "used" and non-constant, are checked if a time of evaluation is set.

Specifically:

  • A function that is "used" and non-constant must have at least one Time of Evaluation (ToE) selected.
  • Timestep evaluated variables (modelled and context variables) that are a) used by a "used" function and b) set to Specify ToE, must similarly have a ToE specified.

A function is considered used if:

  • it has a usage (e.g. on an Inflow node's Additional Flow property);
  • it has Force Evaluate turned on; or
  • it is referenced by a function meeting one of the above conditions (recursively);

Constant functions are excluded from this rule.

Mass BalanceMass balance is checked to ensure it is within the tolerance limit for the entire network and for each catchment, link and node. For example, the rule checks that a node's loss does not exceed inflow. The default tolerance limit is 1 ML, this limit can be changed by navigating to Tools » Application Settings....
Nodes

Storage dimensions are checked to ensure that each level and volume is greater than the previous level and volume. Surface area is checked to ensure that it is greater than or equal to the previous surface area.

Ordering
For constraints, the rule will fail if any constraint exists where:
  • Minimum is infinity; or
  • Minimum is 'NaN' (not a number) eg. divide by 0; or 
  • Maximum has a value and that value is NaN.
     
For orders, the rule will fail if:
  • Any order has a total order volume of infinity; or
  • Any order has a total order volume of NaN; or
  • Any order has an owner that is not part of its upstream ownership system; or
  • Priority ordering is enabled, and:
    • any priority is negative; or
    • any priority is NaN; or
    • the sum of all priorities is not one.

Note, these rules are primarily for debugging purposes, and are set to a notification level of 'None' by default.

OutflowNegative flows are checked for downstream of each node and link.
OwnershipOwnership proportions are checked to ensure they sum to 1
Storage Routing OrderingChecks that the travel time on Storage Routing links is not infinity or negative. This can happen if the representative regulated flow rate for the storage routing link has not been set (in Storage Routing Feature Editor, Avg. Reg Flow = 0 and storage exponent m ≠ 1).