Main Content

SimBiology.Event

Store SimBiology event information

Description

A SimBiology.Event object represents sudden changes in model behavior. An event lets you specify discrete transitions in model component values that occur when a user-specified condition become true. You can specify that the event occurs at a particular time, or specify a time-independent condition.

An event executes its event functions only when its trigger becomes true, and you cannot trigger an event at time = 0 because there is no transition defined for a point in time. For details, see Events in SimBiology Models.

Use dot notation to query the object properties or change properties that are not read-only. You can also use the get and set commands.

The SimBiology Model Builder app also enables you to add events to your model and edit them. For an example, see Incorporate Sudden Changes in Model Behavior Using Event.

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.

Creation

Use addevent (model) to create and add an event to a SimBiology model.

Properties

expand all

Flag to use the event object during simulation, specified as a numeric or logical 1 (true) or 0 (false). If the event object is active, EventFcns are executed when Trigger becomes true during simulation.

Data Types: double | logical

Event functions, specified a character vector, string, string vector, or cell array of character vectors. An event function can be any MATLAB assignment expression that defines what is executed when the event Trigger property becomes true. You can define multiple event functions for each event. Each event function must be an assignment of the form "objectName = expression", where objectName is the name of a valid SimBiology object.

For more information, see How Events Are Evaluated. For examples of event functions, see Specifying Event Functions.

Example: ["speciesA = 100","speciesB = 25"]

Data Types: char | string | cell

SimBiology.Event object name, specified as a character vector or string.

For details on requirements and recommendations for naming SimBiology® components, see Guidelines for Naming Model Components.

Data Types: char | string

Additional information that you can add for SimBiology.Event, specified as a character vector or string.

Data Types: char | string

This property is read-only.

Parent object, specified as a model object.

The object label, specified as a character vector or string.

Tip

Use this property to group objects and then use sbioselect to retrieve. For example, use the Tag property of reaction objects to group synthesis or degradation reactions. You can then retrieve all synthesis reactions using sbioselect. Similarly, for species objects you can enter and store classification information, for example, membrane protein, transcription factor, enzyme classifications, or whether a species is an independent variable. You can also enter the full form of the name of the species.

Data Types: char | string

Event trigger condition, specified as a character vector, string, or function handle. This property is a condition that must become true for an event to execute its event functions (EventFcns).

You can use a combination of relational and logical operators to build a trigger expression, which must return true or false when the expression is evaluated. A trigger can access species, parameters, and compartments.

A trigger expression can also contain the keyword time and relational operators to trigger an event that occurs at a specific time during the simulation. For example, consider an event trigger: time >= x. In this trigger, note that:

  • The units associated with the keyword time are the units for the TimeUnits property of the Configset object associated with the simulation.

  • If x is an expression containing compartments, species, or parameters, then any units associated with the expression must have the same dimensions as the keyword time.

  • If x is a raw number, then its dimensions (and units, if unit conversion is on) are assumed to be the same as the keyword time.

For more information, see How Events Are Evaluated. For examples of event triggers, see Specifying Event Triggers.

Example: "(time >= 5) && (speciesA < 1000)"

Data Types: char | string | function_handle

This property is read-only.

Object type, specified as 'event'. When you create a SimBiology object, the value of Type is automatically defined.

Data Types: char

Data to associate with the object, specified as a numeric scalar, vector, string, or any other MATLAB data type.

The object does not use this data directly, but you can access it using dot notation or get.

Object Functions

copyobjCopy SimBiology object and its children
deleteDelete SimBiology object
displayDisplay summary of SimBiology object
getGet SimBiology object properties
renameRename SimBiology model component and update expressions
setSet SimBiology object properties

Examples

collapse all

Create a simple model with a mass action reaction A -> B, where A and B are species. Also add the reaction rate parameter, p1, with a parameter value of 0.5.

model       = sbiomodel('example');
r1          = addreaction(model,'A -> B');
kl          = addkineticlaw(r1,'MassAction');
p1          = addparameter(model,'p1',0.5);
kl.ParameterVariableNames = 'p1';

Increase the amount of species A to 100 at time = 2. You can do this by adding an event object to the model. You must specify the event trigger (time >= 2), and also the event function, which defines what happens when the event is triggered. In this example, the event function is A = 100.

e1 = addevent(model,'time>=2','A = 100');

Simulate the model, and plot the result.

sd = sbiosimulate(model);
sbioplot(sd);

Figure contains an axes object. The axes object with title States versus Time, xlabel Time, ylabel States contains 2 objects of type line. These objects represent A, B.

Create a SimBiology model.

m1 = sbiomodel("m1");
addspecies(m1,"species",1);
addparameter(m1,"nextEventTime",2,"Constant",0);
addparameter(m1,"eventInterval",1.5);

Add a recurring event at some predefined interval.

addevent(m1,"time > nextEventTime", ...
            ["species = 2*species",...
             "nextEventTime = nextEventTime + eventInterval"] ...
         );

Simulate the model.

cs = getconfigset(m1);
cs.RuntimeOptions.StatesToLog = "species";
sd = sbiosimulate(m1);
sbioplot(sd);

Figure contains an axes object. The axes object with title States versus Time, xlabel Time, ylabel States contains an object of type line. This object represents species.

Version History

Introduced in R2007b