Events in SimBiology Models

Overview

In SimBiology, an event is a discrete transition in value of a quantity or expression in a model. This discrete transition occurs when a customized condition becomes true. The condition can be a specific time and/or a time-independent condition. Such conditions are defined in an Event object.

Event Triggers

An event object has a Trigger property that specifies a condition that must be true to trigger the event to execute.

Typical event triggers are:

A specific simulation time — Specify that the event must change the amounts or values of species or parameters. For example, at time = 5 s, increase the amount of an inhibitor species above the threshold to inhibit a given reaction.
In response to state or changes in the system — Change amounts/values of certain species/parameters in response to events that are not tied to any specific time. For example, when species A reaches an amount of 30 molecules, double the value of reaction rate constant k. Or when temperature reaches 42 °C, inhibit a particular reaction by setting its reaction rate to zero.

Note

Currently, events cannot be triggered at time = 0. However, you can get the event to happen just after time = 0 by using time > timeSmall as the event trigger where timeSmall can be a tiny fraction of a second such as 1.0 picosecond.

Event Functions

An event has an EventFcns property that specifies what occurs when the event is triggered. Event functions can range from simple to complex. For example, an event function might:

Change the values of compartments, species, or parameters.
Double the value of a reaction rate constant.

Specifying Event Triggers

The Trigger property of an event specifies a condition that must become true for an event to execute. Typically, the condition uses a combination of relational and logical operators to build a trigger expression.

A trigger can contain the keyword time and relational operators to trigger an event that occurs at a specific time during the simulation. For example, time >= x. For more information see the Trigger property.

Use MATLAB^® syntax to write expressions for event triggers. Note that the expression must be a single MATLAB statement that returns a logical. No semicolon or comma is needed at the end of an expression. MATLAB uses specific operator precedence to evaluate trigger expressions. Precedence levels determine the order in which MATLAB evaluates an expression. Within each precedence level, operators have equal precedence and are evaluated from left to right. To find more information on how relational and logical operators are evaluated see Relational Operations and Logical (Boolean) Operations.

Some examples of triggers are:

Trigger	Explanation
`(time >= 5) && (speciesA < 1000)`	Execute the event when the following condition becomes true: Time is greater than or equal to `5`, and `speciesA` is less than 1000. Tip Using a `&&` (instead of `&`) evaluates the first part of the expression for whether the statement is true or false, and skips evaluating the second statement if this statement is false.
`(time >= 5) \|\| (speciesA < 1000)`	Execute the event when the following condition becomes true: Time is greater than or equal to `5`, or if `speciesA` is less than 1000.
`(s1 >= 10.0) \|\| (time >= 250) && (s2 < 5.0E17)`	Execute the event when the following condition becomes true: Species, `s1` is greater than or equal to `10.0` or, time is greater than or equal to `250` and species `s2` is less than `5.0E17`. Because of operator precedence, the expression is treated as if it were `(s1 >=10.0) \|\| ((time>= 250) && (s2<5.0E17))`. Thus, it is always a good idea to use parenthesis to explicitly specify the intended precedence of the statements.
`((s1 >= 10.0) \|\| (time >= 250)) && (s2 < 5.0E17)`	Execute the event when the following condition becomes true: Species `s1` is greater than or equal to `10` or time is greater than or equal to `250`, and species `s2` is less than `5.0E17`.
`((s1 >= 5000.0) && (time >= 250)) \|\| (s2 < 5.0E17)`	Execute the event when the following condition becomes true: Species `s1` is greater than or equal to `5000` and time is greater than or equal to `250`, or species `s2` is less than `5.0E17`.

Tip

If UnitConversion is on and your model has any event, non-dimensionalize any parameters used in the event Trigger if they are not already dimensionless. For example, suppose you have a trigger x > 1, where x is the species concentration in mole/liter. Non-dimensionalize x by scaling (dividing) it with a constant such as x/x0 > 1, where x0 is a parameter defined as 1.0 mole/liter. Note that x does not have to have the same unit as the constant x0, but must be dimensionally consistent with it. For example, the unit of x can be picomole/liter instead of mole/liter.

Specifying Event Functions

The EventFcns property of an event specifies what occurs when the event is triggered. You can use an event function to change the value of a compartment, species, or parameter, or you can specify complex tasks by calling a custom function or script.

Use MATLAB syntax to define expressions for event functions. The expression must be a single MATLAB assignment statement that includes =, or a cell array of such statements. No semicolon or comma is needed at the end of the expression.

Following are rules for writing expressions for event functions:

EventFcn	Explanation
`speciesA = speciesB`	When the event is executed, set the amount of `speciesA` equal to that of `speciesB`.
`k = k/2`	When the event is executed, halve the value of the rate constant `k`.
`{'speciesA = speciesB','k = k/2'}`	When the event is executed, set the amount of `speciesA` equal to that of `speciesB`, and halve the value of the rate constant `k`.
`kC = my_func(A,B,kC)`	When the event is executed, call the custom function `my_func()`. This function takes three arguments: The first two arguments are the current amounts of two species (`A` and `B`) during simulation and the third argument is the current value of a parameter, `kC`. The function returns the modified value of `kC` as its output.

Simulation Solvers for Models Containing Events

To simulate models containing events, use a deterministic (ODE or SUNDIALS) solver or the stochastic ssa solver. Other stochastic solvers do not support events. For more information, see Choosing a Simulation Solver.

How Events Are Evaluated

Consider the example of a simple event where you specify that at 4s, you want to assign a value of 10 to species A.

At time = 4 s the trigger becomes true and the event executes. In the previous figure assuming that 0 is false and 1 is true, when the trigger becomes true, the amount of species A is set to 10. In theory, with a perfect solver, the event would be executed exactly at time = 4.00 s. In practice there is a very minute delay (for example you might notice that the event is executed at time = 4.00001 s). Thus, you must specify that the trigger can become true at or after 4s, which is time >= 4 s.

Trigger	EventFcn
`time >= 4`	`A = 10`

The point at which the trigger becomes true is called a rising edge. SimBiology^® events execute the EventFcn only at rising edges.

The trigger is evaluated at every time step to check whether the condition specified in the trigger transitions from false to true. The solver detects and tracks falling edges, which is when the trigger becomes false, so if another rising edge is encountered, the event is reexecuted. If a trigger is already true before a simulation starts, then the event does not execute at the start of the simulation. The event is not executed until the solver encounters a rising edge. Very rarely, the solver might miss a rising edge. An example of this is when a rising edge follows very quickly after a falling edge, and the step size results in the solver skipping the transition point.

If the trigger becomes true exactly at the stop time of the simulation, the event might or might not execute. If you want the event to execute, increase the stop time.

Note

Since the rising edge is instantaneous and changes the system state, there are two values for the state at the same time. The simulation data thus contains the state before and after the event, but both points are at the same time value. This leads to multiple values of the system state at a single instant in time.

Evaluation of Simultaneous Events

When two or more trigger conditions simultaneously become true, the solver executes the events sequentially in the order in which they are listed in the model. You can reorder events using the reorder method. For example, consider this case.

Event Number	`Trigger`	`EventFcn`
1	`SpeciesA >= 4`	`SpeciesB = 10`
2	`SpeciesC >= 15`	`SpeciesB = 25`

The solver tries to find the rising edge for these events within a certain level of tolerance. If this results in both events occurring simultaneously, then the value of SpeciesB after the time step in which these two events occur, will be 25. If you reorder the events to reverse the event order, then the value of SpeciesB after the time step in which these two events occur, will be 10.

Consider an example in which you include event functions that change model components in a dependent fashion. For example, the event function in Event 2, stipulates that SpeciesB takes the value of SpeciesC.

Event Number	`Trigger`	`EventFcn`
1	`SpeciesA >= 4`	`SpeciesC = 10`
2	`time >= 15`	`SpeciesB = SpeciesC`

Event 1 and Event 2 might or might not occur simultaneously.

If Event 1 and Event 2 do not occur simultaneously, when Event 2 is triggered, SpeciesB is assigned the value that SpeciesC has at the time of the event trigger.
If Event 1 and Event 2 occur simultaneously, the solver executes Event 1 first, then executes Event 2. In this example, if SpeciesC = 15 when the events are triggered, after the events are executed, SpeciesC = 10 and SpeciesB = 10.

Evaluation of Multiple Event Functions

Consider an event function in which you specify that the value of a model component (SpeciesB) depends on the value of model component (SpeciesA), but SpeciesA also is changed by the event function.

`Trigger`	`EventFcn`
`time >= 4`	`{'SpeciesA = 10, SpeciesB = SpeciesA'}`

The solver stores the value of SpeciesA at the rising edge and before any event functions are executed and uses this stored value to assign SpeciesB its value. So in this example if SpeciesA = 15 at the time the event is triggered, after the event is executed, SpeciesA = 10 and SpeciesB = 15.

When One Event Triggers Another Event

In the next example, Event 1 includes an expression in the event function that causes Event 2 to be triggered (assuming that SpeciesA has amount less than 5 when Event 1 is executed).

Event Number	`Trigger`	`EventFcn`
1	`time >= 5`	`{'SpeciesA = 10, SpeciesB = 5'}`
2	`SpeciesA >= 5`	`SpeciesC = SpeciesB`

When Event 1 is triggered, the solver evaluates and executes Event 1 with the result that SpeciesA = 10 and SpeciesB = 5. Now, the trigger for Event 2 becomes true and the solver executes the event function for Event 2. Thus, SpeciesC = 5 at the end of this event execution.

You can thus have event cascades of arbitrary length, for example, Event 1 triggers Event 2, which in turn triggers Event 3, and so on.

Cyclical Events

In some situations, a series of events can trigger a cascade that becomes cyclical. Once you trigger a cyclical set of events, the only way to stop the simulation is by pressing Ctrl+C. You lose any data acquired in the current simulation. Here is an example of cyclical events. This example assumes that Species B <= 4 at the start of the cycle.

Event Number	`Trigger`	`EventFcn`
1	`SpeciesA > 10`	`{'SpeciesB = 5', 'SpeciesC = 1'}`
2	`SpeciesB > 4`	`{'SpeciesC = 10', 'SpeciesA = 1'}`
3	`SpeciesC > 9`	`{'SpeciesA = 15', 'SpeciesB = 1'}`

Using Events to Address Discontinuities in Rule and Reaction Rate Expressions

The solvers provided with SimBiology gives inaccurate results when the following expressions are not continuous and differentiable:

Repeated assignment rule
Algebraic rule
Rate rule
Reaction rate

Either ensure that the previous expressions are continuous and differentiable or use events to reset the solver at the discontinuity, as described in Deterministic Simulation of a Model Containing a Discontinuity.