Notices and Notice Rules

What are Notices?

Notices are a way for users to be notified when certain conditions are met in their project. They can be thought of as "alerts" that trigger under specific conditions, and are displayed to the user in the model builder view. Notices are extremely flexible, and can be used to alert users to:

• Divergences between simulated and actual values
• Unrealistic simulation values
• Numeric bugs
• ...among many other things

All notices also have associated "severity" levels, that allow users to specify how important a particular notice is. This makes them suitable not only for critical simulation issues, but also for informational or diagnostic purposes.

Getting Started with Notices

Head over to the new Insights workspace using the new tab on the left-most bar. Select "Add New Notice Rule" to be presented with a form to configure your notice rule.

Configuring you Notice Rule

First, think about the condition which you would like to be notified of. Some examples are listed in the "What are Notices" section above.

For our purposes, let's say we're interested in cases where simulated values and actual values diverge significantly. In order to define a notice rule, we need to quantify our notion of "significant divergence". In general, this would be highly domain-specific, so for the simplicity of this example, we'll use a 10% divergence.

Now that we know when we want to be notified, we need to formalise that into a "predicate". This is just a formula, like you're used to from the element inspector interface, except we can also reference two new special local variables: @simulated and @actual. We'll use these to define our predicate as:

abs(@simulated - @actual) > 0.1 * abs(@actual)

This formula evaluates to true if the simulated value differs from the actual value by more than 10%, and evaluates to false otherwise.

Because this formula evaluates to either true or false, we specify that the predicate evaluates to a "boolean" value. This tells Silico to trigger the notice if the predicate is true, and do nothing otherwise. This setting also determines how we are able to specify the severity level associated to this rule.

Since the predicate evaluates to a boolean value, we need only specify a single severity level, since the notice will either be triggered, or not. For the purposes of this example, specify a severity level of "Error".

All that is left before saving is to specify a meaningful name for this rule. This name will be displayed in the model builder notices panel (see below), so it helps to be descriptive. For this example, use "Divergence from target".

Notices

Once your notice rule is saved, head back to the model workspace. In the status bar at the bottom, you will see a notices indicator, which can be expanded to show how many of your configured notices have been triggered in the current run of the model.

Notice Rule Scopes

A scope determines the context within which each predicate will be evaluated. There is currently a single scope available: element scope. Soon we will support evaluating notices over the whole model.

Element Scope

This scope means each predicate will be evaluated once for each computable element (Variable, Flow or Stock) that exists in the default model -- even those elements within panels.

In this scope, two special local variables are available for use in the predicate:

• @simulated - The simulation value of the scoped element at a given timestep
• @actual - The actual value of the scoped element at a given timestep

All other valid formulae are also permitted. In particular, references to any other model elements are allowed.

Notice Rule Predicate Types

Predicates may evaluate to either a boolean value (true or false) or a numeric value. In either case, users may specify different trigger conditions.

Boolean Predicate

The result of the predicate will be treated as a boolean value. That is, false and 0 values will be treated as false, while true and non-zero values will be treated as true.

Users must select a severity level for the notice if it evaluates to true.

Numeric Predicate

The result of the predicate will be treated as a numeric value. In this case, users should specify ranges of values within which the notice will be triggered, and a corresponding severity level for each range.

Conflicts and overlaps between specified ranges will be resolved by selecting the first range that contains the result.

Notice Rules and Multiple Models

Notices are only evaluated on the default model. The default model is the top-most model in the "Project Structure" sidebar section of the model workspace.

Feature Status

This feature is currently in alpha testing. We would greatly value your testing and feedback. Please don't hesitate to get in touch. We'd also be interested in hearing about potential use cases for this feature outside of what we have imagined.