Dynamic Event

Dynamic events are used to schedule any number of concurrent and independent events. For example, a communication channel which is able to transmit an arbitrary number of messages concurrently can be modeled with the help of dynamic events that are created for each message. Another example is a server with infinite capacity.

Comparing events and dynamic events

There are two types of events: event and dynamic event. Both of them are responsible for scheduling some user-defined actions in the model. The difference between the dynamic event and the event is that the dynamic event deletes itself after its action is executed, whereas the user controlled event survives and can be restarted.

The principal benefit of the dynamic event is that there can be multiple instances of the same dynamic event scheduled concurrently in the model. 

Another feature of dynamic events is the ability to initialize each instance of the dynamic event with some specific data. While scheduling a new instance of a dynamic event, you can pass the required data using the event's parameters. These parameters are accessible in the dynamic event's action. 

However, dynamic events are not so straightforward to use as events, so we recommend using them only in the following cases:

Demo model: Dynamic Event Models Product Delivery

 To define a dynamic event

  1. Drag the  Dynamic Event element from the  Agent palette on the graphical diagram of agent.
  2. Go to the Properties view and change the Name of the event. 
     Since AnyLogic generates a Java class for each dynamic event you add onto the diagram, you should follow the Java naming conventions. Please start name of the dynamic event with an uppercase letter. 
  3. If the action of the dynamic event depends on some specific information, you can pass it to the event using the dynamic event's parameters. Parameters are defined in the Parameters table. Each row of the table specifies one particular parameter, given in the form Name, Type and optional Default value. When creating a new instance of the dynamic event, you may specify the actual parameter values or leave the default ones.
  4. Specify the action you want to be executed on the event occurrence in the Action field. Here you can access the parameters of the dynamic event, if you have defined any. 

Properties

General

Name – The name of the dynamic event. The name is used to identify the dynamic event. This name is used by AnyLogic when it generates the function scheduling a new instance of this dynamic event.
 Since AnyLogic generates a Java class for each dynamic event you add onto diagram, you should follow Java naming conventions. Please start the name of the dynamic event with an uppercase letter. 

Show name – If selected, the name of the dynamic event is displayed on the presentation diagram.

Ignore – If selected, the dynamic event is excluded from the model.

Visible – If selected, the dynamic event is visible on presentation at runtime.

Log to database – If selected, information on all event occurrences will be saved into the model execution log events_log (if logging is turned on in the model's Database properties). 

Parameters

Here you can define the set of optional parameters used to pass some specific information that will be used in the action of the particular instance of the dynamic event. Each row of the table specifies one particular parameter. Every parameter should be given in the following form: NameType and optional Default value. When creating a new instance of the dynamic event, you may specify the actual parameter values or leave the default ones. Since the order of parameters in the table is significant (when scheduling a new instance of a dynamic event, you pass parameter values exactly in the order they are defined in this table), AnyLogic enables the user to change the parameters order by moving them up and down using  and  buttons. To remove a parameter, select the corresponding row in the table and click the  button. 

Action

Here you can type Java code to be executed on the event occurrence. In the code, you can access parameters of the dynamic event if you have defined any.

Scheduling dynamic events

Dynamic events are scheduled differently from events. To schedule one more instance of a dynamic event, use the function automatically generated by AnyLogic for every dynamic event declared on the agent's diagram:
create_dynamic_event_name(
timeout, timeUnits, parameter1, parameter2, … )

Example:

Say, your dynamic event is named ArrivalEvent. To schedule an arrival to occur in 15 minutes from the current model time, call the function:

create_ArrivalEvent(15, MINUTE);

Here you pass the timeout to the function as the first parameter, then you specify the time units for the timeout. To specify time units, you type one of the following time unit constants: MILLISECOND, SECONDMINUTE, HOUR, DAY, WEEK, MONTH, YEAR.

There is also a short function notation, when you specify only the timeout value but omit specifying the time units:

create_ArrivalEvent(15);

In this case the model time units are assumed. If the model time units are hours, the dynamic event ArrivalEvent will be scheduled to occur in 15 hours from the current time moment.

If you have defined any parameters for the dynamic event in its Parameters table, you pass the parameter values to the function using the function arguments, in the same order they appear in the event's Parameters table in the Properties. Say, the DeliveryEvent dynamic event has two parameters: weight and sender. Here is the example of the function call that passes values to the event being created: 

create_DeliveryEvent(2, DAY, 12, this );

You can access the parameters in the event's Action code.

Time counting begins at the moment of creating the instance of a dynamic event. When the event timeout expires, AnyLogic executes the event’s action and then deletes this instance of dynamic event. If the reset() function of the dynamic event is called before expiry, this instance of event is deleted and its action is never performed.

 Please note that using the create_...() function is the only legal way of creating instances of dynamic events. Using Java constructors like new MyDynamicEvent() is prohibited.

Controlling events manually

You can control the currently scheduled instances of a dynamic event programmatically via the following functions:

void reset() - Discards the scheduled occurrence of the event and unregisters this instance of the dynamic event at the agent.

double getRest() - Returns the time remaining before the scheduled occurrence of the event, in model time units.

double getRest(TimeUnits units) - Returns the time remaining before the scheduled occurrence of the event, in given time units
Parameter: units - time unit constant

But unlike an event, which can be accessed simply by its name, there is no easy way to access instances of a dynamic event. 

You can use the function getDynamicEvents() of the agent, which returns a list of all currently active instances of dynamic events within an agent. It can be useful in the case you want e.g. to cancel all these dynamic events. 

However, it would be rather impossible to distinguish one dynamic event from another. Thus, you will need to store references to currently active dynamic events somewhere. You can create your own dynamicEvents collection and put the just created instance of the dynamic event into this collection:

MyDynamicEvent de = create_MyDynamicEvent(7.5);
dynamicEvents.add(de);


Related topics

 Event

 API Reference: DynamicEvent Class