Documentation

Event Object

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 Operations in the MATLAB Programming Fundamentals documentation.

Some examples of triggers are:

TriggerExplanation
'(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.

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:

EventFcnExplanation
'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.

TriggerEventFcn
time >= 4A = 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 NumberTriggerEventFcn
1SpeciesA >= 4SpeciesB = 10
2SpeciesC >= 15SpeciesB = 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 NumberTriggerEventFcn
1SpeciesA >= 4SpeciesC = 10
2time >= 15SpeciesB = 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.

TriggerEventFcn
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 NumberTriggerEventFcn
1time >= 5{'SpeciesA = 10, SpeciesB = 5'}
2SpeciesA >= 5SpeciesC = 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 NumberTriggerEventFcn
1SpeciesA > 10{SpeciesB = 5, SpeciesC = 1'}
2SpeciesB > 4{SpeciesC = 10, SpeciesA = 1'}
3SpeciesC > 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.

Was this topic helpful?