SimBiology®

Changing Model Component Values Using Events

What Is an Event?

Events are used to describe sudden changes in model behavior. An event lets you specify discrete transitions in model component values that occur when a user-specified condition becomes true. You can specify that the event occurs at a particular time, or specify a time-independent condition.

For example, you can use events to activate or deactivate certain species (activator or inhibitor species), change parameter values based on external signals, or change reaction rates in response to addition or removal of species. You can also use an event in a model when you want to replicate an experimental condition, for example, to replicate the addition or removal of an activating agent (such as a drug) to a sample. This section describes events and how they are evaluated.

Use events to define events that occur when a condition becomes true. When you specify a condition in the Trigger you are specifying that the event should be executed when the condition becomes true. Typical triggers are:

• Cause an event to occur at a specific time during simulation — 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.

• Cause an event to occur 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.

The event that is executed when the Trigger becomes true is called an event function (EventFcn). Event functions could 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.

To simulate SimBiology models containing events, use the deterministic sundials solver or the stochastic ssa solver; other solvers do not support events. See Sundials Solvers and Stochastic Solvers for more information.

Procedures   For an example using events in the SimBiology desktop, see Desktop Example — Changing Species Amounts Using an Event in the SimBiology User's Guide For an example of using events at the command line, see addevent in the SimBiology Reference

Back to Top

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 the trigger becomes true and the event is executed. In the figure above 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. 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.

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 executed again. If a trigger is already true before a simulation starts, then the event does not execute the 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; one example of this is when a rising edge follows very quickly after a falling edge, and the step size results in the solver skipping over the transition point.

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

Specifying Event Triggers

A Trigger is a condition that must become true for an event to be executed. Typically, the condition uses a combination of relational and logical operators to build a trigger 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 Operators in the MATLAB Programming Fundamentals documentation.

Some examples of triggers are:

For more information on triggers see Trigger in the SimBiology Reference Guide.

Specifying Event Functions

The event that is executed when a Trigger condition has a rising edge is called an event function (EventFcn). You can use an event function to change the value of a species or a parameter, or you can specify complex tasks by calling an M-file containing a user-defined function or script.

An event function is either a single valid MATLAB expression (without ';' in the expression) or a cell-array of single valid MATLAB expressions. For more information see also EventFcns in the SimBiology Reference Guide. Some examples of event functions include:

Back to Top

Evaluation of Simultaneous Events

When two or more trigger conditions simultaneously become true, the solver executes the events in the order in which they are on the model. You can reorder events using the reorder method at the command-line. Alternatively, in the SimBiology desktop, arrange the rows of events in the order you desire, then right-click and select Reorder Events as Shown in Table. For example, consider a case where:

The solver tries to find the rising edge for these events within a certain level of tolerance. If this results in the two 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 below, stipulates that SpeciesB takes the value of SpeciesC.

Event 1 and Event 2 may or may 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 stores the value of SpeciesC at the rising edge, before any event functions are executed and uses this stored value to assign SpeciesB its value. In the above example if SpeciesC = 15 when the events are triggered, after the events are executed SpeciesB = 15, and SpeciesC = 10.

Back to Top

Evaluation of Multiple Event Functions

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

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 the above example if SpeciesA = 15 at the time the event is triggered, after the event is executed, SpeciesA = 10 and SpeciesB = 15.

Back to Top

When One Event Triggers Another Event

In the example below, 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).

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 (assuming that SpeciesA is below 5) 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.

Back to Top

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. An example of cyclical events is shown below. This example assumes that Species B <= 4 at the start of the cycle.

Back to Top

Changing Model Component Values Using Rules

Desktop Example — Changing Species Amounts Using an Event