Descrete events

Descrete events are used to instantaneously change values of model variables when given conditions are met. For example when model time reaches certain value or when boolean expression becomes true. Generally event consists of two parts: trigger - which defines conditions of event and execution - actions which should be performed after event is triggered. In BioUML events are handling according to latest SBML specification.

Events handling is independent from time course simulation and can be used in different types of models including ODE solving, stochastic simulation, algebraic models. Solver should be able to recognize that event was triggered, calculate specific time point at which it happened and stop simulation. Special wrapper solver EventLoopSimulator takes control, processes triggered events changes model variable values, reinits main solver and restarts it. Most solvers which are able to detect events have option Locate event which is set to true by default.

Logic of events can be quite complicated.

Event attributes:

• Trigger specifies conditions for event to occur. It is a mathematicla boolean expression from model variables. If during simulation this expression transits from false to true - event is considered as triggered. It is usually better to formulate trigger in terms of inequalities: time > 9, x+y > z.
• Assignments - list of assignments which should be performed when event is executed. Each assignment consists of variable and mathematical expression. When event is executed, expressions are evalueated and results are assigned to variables.
• Priority - defines order of events execution in the case when several events are to be executed at the same time. Prioity is a evaluated expression from model variables and is recalculated each time it is checked.
• Delay - defines time delay between event triggering and execution
• Use trigger time values - if true then assignment expressions are calculated using values of variables at the time of triggering. If false - at the time of execution.
• Persistent tigger - if true then once event is triggered - it will be executed no matter what happends before execution time. If false and event tigger transits from true to false after event is triggered then event is considered switched off and will not be executed. Note that if then trigger will transit from false to true again - event will be triggered again.
• Trigger initial value - defines whether event may be triggered at the start of the simulation (i.e. time = 0). If set to true then event can not be triggered at time = 0 even if Trigger expression is true at this time. If set to false and trigger experssion evaluates to true at time = 0 then event will be triggered.

Processing of events done by EventLoopSimulator goes as follows:

1. Check which events were triggered. Add all these events to the pool of pending events. 2. Calculate prioirty for each of triggered events - choose on with the highest priority, or if there are several events with maximal priority - choose one of them randomly. 3. Process chosen event 4. Recalculate triggers of all other events. 5. If it was not triggered before step 3 but is triggered now (it was switched on by executed event) - add it to the pool of pending events. 6. If event has Persistent trigger = false and its trigger expression evaluates to false - remove it from the pool (it was switched off). 7. If list of pending events is empty - reinit solver and start it with new values. Else - goto 2.

It should be noted that this algorithm can potentially never end - events may form infinite loop triggering each other, so model creator should be cautious while using events in models.