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 anEvent object.

Event Triggers

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

Typical event triggers are:

Event Functions

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

Specifying Event Triggers

TheTriggerproperty 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 keywordtimeand relational operators to trigger an event that occurs at a specific time during the simulation. For example,time >= x. For more information see theTriggerproperty.

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 seeRelational OperationsandLogical (Boolean) Operations.

Some examples of triggers are:

Specifying Event Functions

TheEventFcnsproperty 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:

Simulation Solvers for Models Containing Events

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

How Events Are Evaluated

Consider the example of a simple event where you specify that at4s, you want to assign a value of10to speciesA.

Attime = 4 sthe trigger becomes true and the event executes. In the previous figure assuming that0is false and1is true, when the trigger becomes true, the amount of speciesAis set to10. In theory, with a perfect solver, the event would be executed exactly attime = 4.00 s. In practice there is a very minute delay (for example you might notice that the event is executed attime = 4.00001 s). Thus, you must specify that the trigger can become true at or after4s, which istime >= 4 s.

The point at which the trigger becomes true is called arising edge. SimBiology^®events execute theEventFcnonlyat 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 tracksfalling 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.

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 thereordermethod. For example, consider this case.

解算器试图找到的前沿events within a certain level of tolerance. If this results in both events occurring simultaneously, then the value ofSpeciesBafter the time step in which these two events occur, will be25. If you reorder the events to reverse the event order, then the value ofSpeciesBafter the time step in which these two events occur, will be10.

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 thatSpeciesBtakes the value ofSpeciesC.

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

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), butSpeciesAalso is changed by the event function.

The solver stores the value ofSpeciesAat the rising edge and before any event functions are executed and uses this stored value to assignSpeciesBits value. So in this example ifSpeciesA = 15at the time the event is triggered, after the event is executed,SpeciesA = 10andSpeciesB = 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 thatSpeciesAhas amount less than5when Event 1 is executed).

When Event 1 is triggered, the solver evaluates and executes Event 1 with the result thatSpeciesA = 10andSpeciesB = 5. Now, the trigger for Event 2 becomes true and the solver executes the event function for Event 2. Thus,SpeciesC = 5at 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

在一些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 pressingCtrl+C. You lose any data acquired in the current simulation. Here is an example of cyclical events. This example assumes thatSpecies B <= 4at the start of the cycle.

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:

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