Handling events

[kwabenantim]

Summary

From SBML Level 3 v2:

Model has an optional list of Event objects that describe the time and form of instantaneous, discontinuous state changes in the model.

Mechanism

the operation of every event is divided into two phases ... when the event is triggered and ... when the event is executed.
...
If a Delay ... is present, these moments are separated by simulation time.
...
An event only triggers when the expression within its Trigger ... makes the transition ... from “false” to “true”. The event will trigger again ... when the trigger makes the transition from “false” to “true”;
...
The Priority ... influences the order in which ... to perform the assignments ....

Special Flags

The attribute useValuesFromTriggerTime allows a model to indicate the moment at which the event’s assignments are to be evaluated ... “true” indicates ... the moment the event is triggered ... “false” means ... the moment the event is executed.
...
The behavior at the ... start of simulation ... is determined in part by the boolean flag initialValue ... “true” means the trigger expression is taken to have the value “true” immediately prior to t = 0.
...
If the boolean attribute persistent has a value of “true”, then once the event is triggered ... its assignments are always performed...

[kwabenantim]

Following the practice in #23, Delays will not be supported, which also means useValuesFromTriggerTime will not be supported.

An "Unsupported Feature" error message will throw if a model uses any of these elements.

[kwabenantim]

initialValue = "false” will not be supported as its purpose is to allow events to trigger at the start of the simulation, which will result in "Stopping event is true for initial condition" errors in Chaste.

[kwabenantim]

graph LR;
    START( start )
    START --> DO_1
    DO_1[ triggered=true ]
    DO_1 --> Q_1
    Q_1{ condition <br/> true? }
    Q_1 -- Y --> Q_2
    Q_1 -- N --> DO_2
    Q_2{ already <br/> triggered? }
    Q_2 -- Y --> STOP
    Q_2 -- N --> DO_3
    DO_2[ triggered=false ]
    DO_2 --> STOP
    DO_3[ triggered=true <br/> update state ]
    DO_3 --> STOP
    STOP( next call ) --> Q_1

     classDef orange fill:#f4a460,stroke:#333,stroke-width:2px;
     classDef green fill:#66cdaa,stroke:#333,stroke-width:2px;
     classDef purple fill:#dda0dd,stroke:#333,stroke-width:2px;
     class START,STOP orange
     class Q_1,Q_2 green
     class DO_1,DO_2,DO_3 purple

Loading

[kwabenantim]

Simultaneous and cascading events

From SBML Level 3 v2 4.12.7:

Consider an Event ... which ... makes a transition ... at times t1 and t2. The EventAssignment ... will have effect at t1 ... and t2 ...

It is entirely possible for two events to be executed simultaneously, and it is possible for events to trigger other events ...

Event re-test loop

A software package should retest all event triggers after executing the assignments from a given event in order to account for the possibility that the assignments cause another event trigger to transition from “false” to “true”. This check should be made after each individual Event object’s execution, even when several events are to be executed simultaneously.

Cascading events

... it is assumed that the order in which the events occur is resolved ... When an event X triggers another event Y ... then ... Y is added to the ... set of simultaneous events ... pending execution. ... X and Y form a cascade of events at the same point in simulation time. ... Y may have a special priority if it contains a Priority ...

Infinite cascades

All events ... are open to being in a cascade. The position ... in the event queue does not affect whether it can be in the cascade: ... Y can be triggered whether it is before or after X in the queue. A cascade ... can be potentially infinite ... when this occurs a simulator should indicate this has occurred—it is incorrect for a simulator to break a cascade arbitrarily and continue the simulation without at least indicating that the infinite cascade occurred.

Ordering of simultaneous events

Simultaneous events having no defined priorities are executed in an undefined order ... A given simulator may use any algorithm to choose an order as long as every event is executed exactly once.

Events with defined priorities are executed in the order implied by their Priority ..., with events having higher priorities being executed ahead of events with lower priorities, and events with identical priorities being executed in a random order with respect to one another (as determined at run-time by some random algorithm equivalent to coin-flipping ... Events without Priority ... must be inserted into the queue in some fashion, but the algorithm used to place it in the queue is undefined....

Simultaneous event assignments

A model variable that is the target of one or more event assignments can change more than once when simultaneous events are processed at some time point t. The model’s behavior (output) for such a variable is the value of the variable at the end of processing all the simultaneous events at time t.