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

Active — Flag to use event object during simulation

true or 1 (default) | false or 0

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

EventFcns — Event functions

'' (default) | character vector | string | string vector | cell array of character vectors

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

Name — SimBiology.Event object name

character vector | string

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

Notes — Additional information

empty character array (default) | character vector | string

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

Data Types: char | string

Parent — Parent object

model object

This property is read-only.

Parent object, specified as a model object.

Tag — Object label

empty character array (default) | character vector | string

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

Trigger — Event trigger condition

'' (default) | character vector | string | function handle

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

Type — Object type

'event' (default)

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

UserData — Data to associate with object

scalar | vector | string | ...

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

copyobj	Copy SimBiology object and its children
delete	Delete SimBiology object
display	Display summary of SimBiology object
get	Get SimBiology object properties
rename	Rename SimBiology model component and update expressions
set	Set SimBiology object properties

Examples

Add an Event

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);

Add Recurring Event to SimBiology Model

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);

Version History

Introduced in R2007b

R2024a: Having duplicate model component names is no longer allowed

• When you load a model that contains duplicate names, SimBiology automatically updates those names. SimBiology disambiguates the duplicate names by adding a suffix "_N", where N is the first positive integer that results in a unique name. If there is an existing suffix, N will be incremented from that suffix. For example, if there are two model components named x_3, the function updates one of the names to x_4. If the existing suffix has leading zeros, the function omits the zeros in the new name. For instance, if x_003 is a duplicate name, it gets renamed to x_4. However, the function assumes that names with leading zeros and without leading zeros are different. For instance, x_005 and x_5 are considered to be different names.

• SimBiology issues an error if multiple model components (model, compartment, species, parameter, reaction, rule, event, observable, dose, and variant) have the same name. Within a single model, these components are required to have unique names even when they are of different types with the following two exceptions:

  • Species in different compartments can have the same name.

  • Parameters can have the same name if they are scoped to different parents. Specifically, you can use the same name for a model-scoped parameter and reaction-scoped parameters, where each reaction-scoped parameter belongs to a different reaction.

  For details on how to reference model component names in expressions, see Guidelines for Referencing Names in Expressions.

R2022b: Having duplicate model component names issues a warning

SimBiology issues a warning if multiple model components have the same name.

R2022a: Having duplicate model component names will not be allowed in a future release

SimBiology will not allow you to have duplicate names for model components within a model.