Descrete events - Revision history

Axec@dote.ru at 09:16, 15 May 2023

2023-05-15T09:16:03Z

Axec@dote.ru: /* Behavior details */

2017-02-10T10:38:57Z

‎Behavior details

Axec@dote.ru at 10:15, 10 February 2017

2017-02-10T10:15:55Z

Axec@dote.ru at 10:15, 10 February 2017

2017-02-10T10:15:00Z

Axec@dote.ru at 09:26, 10 February 2017

2017-02-10T09:26:17Z

Axec@dote.ru at 09:11, 10 February 2017

2017-02-10T09:11:38Z

Axec@dote.ru at 09:06, 10 February 2017

2017-02-10T09:06:40Z

Axec@dote.ru: Created page with "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 e..."

2017-02-10T07:54:10Z

Created page with "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 e..."

New page

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: <code>time > 9</code>, <code>x+y > z</code>.
*'''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.

← Older revision		Revision as of 09:16, 15 May 2023
Line 4:		Line 4:

	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.		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.
		+
		+	==Basics==
		+	In general event for model with two variables A and B and two assignments looks like this:
		+	<code>
		+	:When f(time, A, B)
		+	:do:
		+	::A = g_1(time, A, B)
		+	::B = g_k(time, A, B)
		+	</code>
		+
		+	Here f is an event trigger - boolean function taking values '''true''' or '''false''', g_1, g_2 are assignment functions.
		+
		+	Important thing is that functions g_1(time, A, B) and g_2(time, A, B) are calculated '''before''' assigment to corresponding variables. Thus order of assignments '''does not matter''' and it is possible to create events like:
		+	<code>
		+	:When time > 10
		+	:do:
		+	::A = B
		+	::B = A
		+	</code>
		+
		+	Here when model time will exceed 10 - variables B and A will be swapped
		+
		+	<code>
		+	:When B > 10
		+	:do:
		+	::A = A + 1
		+	</code>
		+	Here variable A will be incremented
		+
		+	Another important issue is that event is considered triggered when value of trigger function '''changes''' value from '''false''' to '''true''' thus it is strongly discouraged to use triggers like f(time, A, B) == 0 because time interval with '''true''' value may be too small (or even be a single time point) and may be simply missed during simulation. If trgger takes form f(time, A, B) > 0 simulator will detect that f changed its sign and then will try to find exact time point at which it happened (which corersponds to f(time, A, B) = 0).
		+
		+	It also should be noted that in boolean values opeartors '''&&''', '''\|\|''' and '''==''' should be used instead of '''&''', '''\|''' and '''='''.
		+
		+	==Multiple events==
		+	More than one event may be triggered at the same if this happens - their '''priorities''' defines order of their execution. If two events have the same priority - they will be executed in unpredictable order. By default those events can not affect each other as assignment values will be calculated before either of them executed. However oe event can activate another one as in given example first evnt will activate second:
		+	<code>
		+	:When time > 10
		+	:do:
		+	::A = 5
		+	</code>
		+
		+	<code>
		+	:When time > 10 && A == 5
		+	:do:
		+	::B = 5
		+	</code>
		+
		+	Moreover events may activate one another in (posssibili infinite) event cascade

	==Behavior details==		==Behavior details==

@@ Line 6: / Line 6: @@
 ==Behavior details==
 Logic of events can be quite complicated. Time point at which event should be executed may be different totime point at which it is executed due to preset time delay. Events execution may affect other events causing them to trigger or deactivating already triggered events. If several events are to be executed at the same time - order of execution is managed according to their priorities which are represented by mathematical expressions and may also be changed when other events are executed. It should be noted that events may form infinite loop triggering each other, so model creator should be cautious while using events in models.
 When event is executed, for each assignment, right hand side is evaluated and assigned to correspondent variable. Values of variables used in right hand side are fixed before execution and thus order of assignments does not matter. Let's consider example:
@@ Line 20: / Line 41: @@
 :After event execution: x = 7, y = -1, z = 4.
 </code>
 ==Implementation==

@@ Line 41: / Line 41: @@
 Thus each event is executed at the very same time point when it was triggered, all ''preparational'' events are executed before any ''executional'' and order of ''executional'' events is defined by priorities.
-Let's consider what happends with event discussed earlir:
+Let's consider what happends with event discussed earlier:
-<code> Preparational event
+<code>
 :Trigger: x > 1
 :Priority: Infinity
@@ Line 52: / Line 53: @@
 </code>
-<code> Executional event
+<code>
 :Trigger: time > DelayedTime
 :Priority: y + z

@@ Line 10: / Line 10: @@
 When event is executed, for each assignment, right hand side is evaluated and assigned to correspondent variable. Values of variables used in right hand side are fixed before execution and thus order of assignments does not matter. Let's consider example:
 <code>
-:Before event execution: x = 1, y = 2, z = 3.
+:Trigger: x > 1
 :Assignments:
 ::x = y + 5,
 ::y = x - 2,
 ::z = z + 1.
 :After event execution: x = 7, y = -1, z = 4.
 </code>
@@ Line 22: / Line 25: @@
 *'''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: <code>time > 9</code>, <code>x+y > z</code>.
 *'''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.
+*'''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. If prioirty is not set - event will have minimal priority ('''Note:''' behaviour for this case is not specified by SBML specification and left to particular software to decide).
 *'''Delay''' - defines time delay between event triggering and execution. Delay should be assgined by numerical value and can not be changed during simulation.
-*'''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.
+*'''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. Note: these values may be different due to two reasons:
 *'''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. <code>time = 0</code>). If set to ''true'' then event can not be triggered at <code>time = 0</code> even if Trigger expression is true at this time. If set to ''false'' and trigger experssion evaluates to ''true'' at <code>time</code> = 0 then event will be triggered.
 ==Implementation==
 Processing of events done by EventLoopSimulator goes as follows:

@@ Line 7: / Line 7: @@
 ==Behavior details==
 Logic of events can be quite complicated. Time point at which event should be executed may be different totime point at which it is executed due to preset time delay. Events execution may affect other events causing them to trigger or deactivating already triggered events. If several events are to be executed at the same time - order of execution is managed according to their priorities which are represented by mathematical expressions and may also be changed when other events are executed. It should be noted that events may form infinite loop triggering each other, so model creator should be cautious while using events in models.
 Event attributes:

@@ Line 22: / Line 22: @@
 Processing of events done by EventLoopSimulator goes as follows:
-. Check which events were triggered. Add all these events to the pool of pending events.
+# Check which events were triggered. Add all these events to the pool of pending events.
-. Calculate prioirty for each of triggered events - choose one event with the highest priority, or if there are several events with maximal priority - choose one of them randomly.
+# Calculate prioirty for each of triggered events - choose one event with the highest priority, or if there are several events with maximal priority - choose one of them randomly.
-. Process chosen event
+# Process chosen event
-. Recalculate triggers of all other events.
+# Recalculate triggers of all other events.
-. 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.
+# 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.
-. If event has '''Persistent trigger = false''' and its trigger expression evaluates to false - remove it from the pool (it was switched off).
+# If event has '''Persistent trigger = false''' and its trigger expression evaluates to false - remove it from the pool (it was switched off).
-. If list of pending events is empty - reinit solver and start it with new values. Else - goto 2.
+# If list of pending events is empty - reinit solver and start it with new values. Else - goto 2.