Events and Event Actions

In a discrete-event simulation, an event is an instantaneous incident that may change a state variable, output, or the occurrence of other events. By using SimEvents^®, you can create custom actions that happen when an event occurs for an entity such as when an entity enters or exits a block.

Overview of Events

In SimEvents, you can specify event actions based on entity status. A typical event sequence in a SimEvents model is:

1. An entity is generated.

2. The entity advances from an Entity Generator block to an Entity Server block.

3. The Entity Server block completes the service of an entity.

4. The entity exits Entity Server block and enters an Entity Terminator block.

5. The entity is destroyed.

When an entity is created, enters or exits a block, or is serviced or destroyed, the entity changes status. You can use certain SimEvents library blocks to create event actions that trigger when these status changes occur. You can write event actions by using:

• MATLAB^® code that performs calculations.

• Simulink^® function calls that call a function that performs computations.

For more information about event action languages, see Event Action Languages and Random Number Generation.

Write Custom Code for Event Actions

To create event action code and language, in a SimEvents block, select the Event actions tab and choose the event that invokes the action. For example, in the Entity Generator block, there are two events provided to invoke event actions, Generate and Exit. The event actions are triggered when an entity is generated or exits the block.

If you click the Generate event, you can write your code in the Generate action field.

When you use event actions:

• The entities are available as MATLAB structures and include structure fields that represent values of the entity attributes.

• Reserved fields, such as entity ID and entity priority, are also available in a separate MATLAB structure called entitySys.

For an example of using event actions, see Manage Entities Using Event Actions.

SimEvents Blocks that Include Event Actions

You can see what event actions are available on the Event actions tab of a block. These are the possible events for which you can create actions.

Entity Generator Block	Entity Queue Block	Entity Server Block	Entity Terminator Block	Resource Acquirer Block	Entity Batch Creator Block
Entity generation	Entity entry to queue block	Entity entry to server block	Entity entry to terminator block	Entity entry to acquirer block	Entity entry to batch block
Entity exit from block	Entity exit from block	Service completion of entity	N/A	Entity exit from acquirer block	Entity batch generation
N/A	Entity is blocked	Entity exit from block	N/A	Entity is blocked	Entity exit from block
N/A	N/A	Entity is blocked	N/A	N/A	Entity is blocked
N/A	N/A	Entity is preempted	N/A	N/A	N/A

This illustration shows the flow of actions as entities move through a discrete-event system simulation.

Notes:

• Entity entry, exit, and blocking actions are performed as part of an entity forward event.

• Service completion action is performed following a timer event.

• Entity termination event performs a destruction action.

You can also modify the entity attributes (entityName.attributeName), entity priorities (sys.entity.priority), and entity IDs (sys.entity.id). However, you cannot change the entity attributes or system properties (entitySys) for exit actions. Attempting to change these values causes an error at simulation.

Using the Event Actions Assistant

The Event Actions Assistant helps you create code for repeated sequence of event actions or random event actions according to a statistical distribution. For example, to access the assistant in an Entity Generator block:

1. Open the block and select the Event actions tab and select the Generate event action.

2. In the Generate action field, click the Insert pattern button.

Suppose that you want to generate entities and assign random attribute values to them. The values are generated from a uniform distribution between 0 and 1.

To achieve this behavior:

1. Select Random number.

2. To select a uniform distribution, set the Distribution parameter to Uniform.

3. By default, the Minimum and the Maximum parameters are specified as 0 and 1, respectively.

4. To attach the values to the entity attribute Attribute1, set the Assign output to parameter to entity.Attribute1.

The assistant creates the code.

The code creates a persistent variable for the seed. Then a random value is attached to entity.Attribute1. After you define an action, an asterisk (*) appears in the Event actions tab to indicate that a code is called for that event. In this case, an asterisk is displayed after the Generate event action.

For more information on the event actions assistant, see Event Action Languages and Random Number Generation.

Track Events with Event Calendar

SimEvents does not represent events graphically. Instead, the SimEvents software maintains an event calendar that schedules events. You can use the Event Calendar to observe events when you debug a SimEvents model. For more information, see Debug SimEvents Models.

You can also interact with the event calendar by using simevents.SimulationObserver methods. You can create a custom event observer using this class and its methods. For more information, see Use SimulationObserver Class to Monitor a SimEvents Model.

Visualize Event Actions

When you create an event action, {...} badge appears on the block to indicate that the action is created. The badges that appear depending on which event actions have associated code.

For instance, this illustration shows an Entity Queue block with event actions that are invoked by the entity entry and exit from the block.

When you hover over the badge, you can see the event action. For example, this illustration depicts an entity exit action.

Double-clicking the badge directly opens the Event actions tab of the block.

Preventing Livelock for Large Finite Numbers of Simultaneous Events

Simultaneous events are events that occur at the same simulation clock time. Events scheduled on the event calendar at times T and T+Δt are considered simultaneous if 0 ≤ Δt ≤ 128*eps*T, where eps is the floating-point relative accuracy in MATLAB software and T is the simulation time. If your simulation creates a large number of simultaneous events, this number might be an indication of an unwanted livelock situation. During a livelock situation, a block returns to the same state infinitely often at the same time instant. SimEvents software prevents livelock with these limits:

• SimEvents limits the maximum number of simultaneous events per block to 5,000.

• SimEvents limits the maximum number of simultaneous events per model to 100,000.