Event

Event is the simplest way to schedule some action in the model. Thus, events are commonly used to model delays and timeouts. Sometimes you do the same using timed transitions in statecharts, but events might be more efficient.

There are three types of events:

• Timeout triggered event. It is used when you need to schedule an action at some particular moment of time (or some particular date). The event occurs exactly in timeout time after it is started. Timeout triggered event has even more features: you can specify that it expires either once or cyclically, or is fully controlled by the user.
• Rate triggered event. It is used to model a stream of independent events (Poisson stream). It is frequently needed to model arrivals: e.g. customer arrivals in queuing systems, transaction arrivals in server-based network models, etc.
• Condition triggered event. It is used when you want to monitor a certain condition and execute an action when this condition becomes true.

There is another type of event defined with another model element - 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.

To create an event

1. Drag the Event element from the Agent palette onto the agent's graphical diagram.
2. Once the event is created, you can specify its name in the text line editor opened on the right of the element in the graphical editor. When finished, press Enter and go to the Properties view.
3. Specify the event’s action in the Action section. There you can write Java code to be executed on the event occurrence. Probably it would be more convenient to define this code as a function and place the function call here.
4. Using the Trigger type drop-down list, choose the type of event and configure the event using the specific properties of this particular event type.

General properties

Name – The name of the event. The name is used to identify and access the event.

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

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

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

Trigger type – The event's trigger type:

• Timeout – The event is timeout triggered. The event occurs according to the chosen Mode.
• Rate – The event is rate triggered. The event occurs with the specified Rate.
• Condition – The event is condition triggered. The event occurs when the specified boolean Condition evaluates to true.

Mode – [Visible if Trigger type: Timeout] Choose here the mode of the timeout triggered event:

• User control – The event will work in manual mode. It will occur only when the user calls the event’s restart function passing the timeout as the argument, for instance myEvent.restart(15).
  If the timeout is fixed, you can define it once in the Timeout property and simply call myEvent.restart() without specifying the timeout as a function parameter.
• Occurs once – The event will occur only once exactly in the specified First occurrence time (absolute) or Occurrence date. You can define the occurrence time as a calendar date (choose Use calendar dates) or as a number of model time units to be passed from the model start (choose Use model time).
  Here you define the absolute time and in the case the event will be created after the specified time, it will never occur.
• Cyclic – The event will occur cyclically. You define the First occurrence time (absolute) or Occurrence date and the Recurrence time for an event. The first occurrence time can be defined either as a calendar date (choose Use calendar dates), or as a number of model time units to be passed from the model start (choose Use model time).
  You define absolute times. If you want to use relative times (i.e. count the first occurrence time from the moment this event will be created), use time() function in the First occurrence time (absolute) property. time() will refer to the moment when event was created.

Timeout – [Visible if Trigger type: Timeout and Mode: User control] The expression evaluating the timeout that should pass from the moment when the user starts the event by calling its restart() function.

Use model time - [Visible if Trigger type: Timeout and Mode: Occurs once or Cyclic] If selected, the event will occur at the specified model time.

Use calendar dates - [Visible if Trigger type: Timeout and Mode: Occurs once or Cyclic] If selected, the event will occur at the specified calendar date.

Occurrence time (absolute) – [Visible if Trigger type: Timeout, Mode: Occurs once and Use model time is selected] The absolute time of event occurrence defined as a number of model time units to be passed from the model start.

Occurrence date - [Visible if Trigger type: Timeout, Mode: Occurs once or Cyclic and Use calendar dates is selected] The calendar date and time of the event.

First occurrence time (absolute) – [Visible if Trigger type: Timeout, Mode: Cyclic and Use model time is selected] The absolute time of the first occurrence of the cyclic event, defined as a number of model time units to be passed from the model start.

Recurrence time – [Visible if Trigger type: Timeout and Mode: Cyclic] The recurrence time of the cyclic event.

Rate – [Visible if Trigger type: Rate] The rate triggering the event. Event will occur with the timeout distributed exponentially with the parameter rate, e.g. if the rate is 5, event will occur on average 5 times per time unit.

Condition – [Visible if Trigger type: Condition] The condition triggering the event. Event will occur when the specified Boolean expression is true.

Action

Here you can type Java code to be executed on event occurrence.

Timeout triggered event is used when you need to perform an action at some particular moment of time (or on some particular date). Such an event occurs exactly in Timeout time after it is started.

Timeout triggered event has several work modes, allowing the user to efficiently solve various tasks, e.g.:

• Scheduling periodic events.

  Cyclic event mode enables the user to perform some actions periodically, e.g. every morning, or quarterly. Use cyclic events in synchronous models. The figure below shows the simplest example of a cyclic event performing some action daily:

  

  Another (probably, more illustrative) use case. Let's assume we need to perform some actions at the start of a new shift (at 8 A.M.) in a factory model. Such behavior can be easily implemented using a cyclic event. In this case, if your model time units are hours, you simply specify 8 as the First occurrence time (absolute) and 24 as the Recurrence time. Cyclic event can deal with calendar dates as well. In this case you specify the calendar date, when you want this event to occur for the first time, and specify the event's Recurrence time (here you can use AnyLogic time functions (second(), minute(), hour(), day(), week()), returning time values, according to the current time unit setting). For example, to set up a weekly event, type there week().

• Scheduling some action at the very beginning of simulation.

  You may need to perform some actions just at the very beginning of the simulation, but after the agent's Startup code is already performed. Such the behavior can be implemented using the Occurs once event mode and the Timeout set to 0.

• Scheduling some action at particular time moment from the present situation.

  This kind of behavior can be implemented using the User control event mode. Such the event is manually controlled by the user via its API. To schedule a event, you call its function restart(), specifying the timeout value as a parameter:

  

To add a timeout triggered event

1. Drag the Event element from the Agent palette onto the graphical diagram of agent.
2. Once the event is created, you can specify its name in the text line editor opened on the right of the element in the graphical editor. When finished, press Enter and go to the Properties view.
3. Choose Timeout from the Trigger type drop-down list.
4. Specify the event’s action in the Action section. There you can write Java code to be executed on the event occurrence. Probably it would be more convenient to define this code as a function and just place the function call here.
5. Choose the event mode from the Mode drop-down list:
   • User control – the event will work in manual mode. It will occur if and only if user calls the event’s restart() function passing the timeout as the argument, for instance myEvent.restart(15). Demo model: Event for Automatic Shutdown Open the model page in AnyLogic Cloud. There you can run the model or download it (by clicking Model source files).
     If the timeout is fixed and known beforehand, you can define it once in the Timeout property and simply call myEvent.restart() without specifying the timeout as a function parameter.
   • Occurs once – the event will occur only once exactly in the specified Occurrence time (absolute) or Occurrence date. You can define the occurrence time as a calendar date (choose Use calendar dates) or as a number of model time units to be passed from the model start (choose Use model time). Demo model: Slow Down Simulation on Particular Date Open the model page in AnyLogic Cloud. There you can run the model or download it (by clicking Model source files).
     Here you define the absolute time and in the case the event will be created after the specified time, it will never occur.
   • Cyclic – the event will occur cyclically. Using the controls below, you define the First occurrence time (absolute) or Occurrence date and the Recurrence time for an event. The first occurrence time can be defined either as a calendar date (choose Use calendar dates), or as a number of model time units to be passed from the model start (choose Use model time). Demo model: Event Writes to the Log Open the model page in AnyLogic Cloud. There you can run the model or download it (by clicking Model source files).
     You define absolute times. If event will be created after the specified first occurrence time, the model will schedule the first occurrence time in the past and then will successively increment it with Recurrence time. The first time that will exceed the current model time will be used as the actual first occurrence time. The next occurrence times will be counted as it should be by adding the defined Recurrence time. If you want to use relative times (i.e. count the first occurrence time from the moment this event will be created), use the time() function in the First occurrence time (absolute) property. time() will refer to the moment when this event was created.

Controlling events

Function	Description
boolean isActive()	Returns true, if the event is currently scheduled, false otherwise.
void reset()	Cancels the currently scheduled event, if any. In case the event is Cyclic, the cycle would not resume until restart() or restart(double t) is called.
void restart()	Cancels the currently scheduled event, if any, and schedules the next occurrence according to the Timeout specified.
void restart(double timeout)	Cancels the currently scheduled event, if any, and schedules the next occurrence in time timeout. Timeout is specified in model time units. If the event is Cyclic, it will then continue occurring at the original timeout/rate. timeout - time (from the function call moment), in which the event will be scheduled.
void restart(double timeout, TimeUnits units)	Cancels the currently scheduled event, if any, and schedules the next occurrence in time timeout. Timeout is specified in given time units. If the event is Cyclic, it will then continue occurring at the original timeout/rate. timeout - time (from the function call moment), in which the event will be scheduled. units - time unit constant Example: event.restart(10, MINUTE) schedules event occurrence in 10 minutes from the current moment of model time.
void restartTo(double time)	Cancels the currently scheduled event, if any, and schedules the next occurrence at the absolute model time time. Timeout is specified in model time units. If the event is Cyclic, it will then continue occurring at the original timeout/rate. This method looks similar to the restart(time - time()) call but it is actually different because it eliminates numeric calculation error which may occur on any machine. time - model time (absolute), at which the event will be scheduled.
void restartTo(double time, TimeUnits units)	Cancels the currently scheduled event, if any, and schedules the next occurrence at the absolute model time time. Timeout is specified in given time units. If the event is Cyclic, it will then continue occurring at the original timeout/rate. This method seems to be like the call restart(time - time()) but it is different because it eliminates numeric calculation error which may occur on any machine. time - model time (absolute), at which the event will be scheduled. units - time unit constant
void restartTo(Date date)	Cancels the currently scheduled event, if any, and schedules the next occurrence at the model date date. If the event is Cyclic, it will then continue occurring at the original timeout/rate. This function is similar restart(toTimeoutInCalendar(...)) but it eliminates numeric calculation error which may occur on any machine. date - model date, at which the event will be scheduled.
void suspend()	Cancels the currently scheduled event, if any, and remembers the remaining time so that it can be resumed by calling resume(). If the event is not scheduled at the time of calling suspend(), the subsequent resume will result in nothing. You should not call this function (i.e. should not try to suspend the event) from its own action code: it will have the effect of reset().
void resume()	Re-schedules the previously suspended event in the remaining time. Does nothing if event was never suspended or was reset or restarted after it was last suspended. double getRest() - Returns the time remaining before the scheduled occurrence of the event, in model time units. If the event is not scheduled, the function returns infinity.
double getRest(TimeUnits units)	Returns the time remaining before the scheduled occurrence of the event, in given time units. If the event is not scheduled, the function returns infinity. units - time unit constant Example: event.getRest(MINUTE) will return the remaining time in minutes.

Rate triggered event is used to model a stream of independent events (Poisson stream). It is frequently needed to model independent arrivals: e.g. customer arrivals in queuing systems, transaction arrivals in server-based network models, etc.

Such an event is executed periodically with time intervals distributed exponentially with the parameter rate, i.e. if the rate is 5, the event will occur on average 5 times per time unit.

The figure below illustrates a rate triggered event modeling customer arrivals. The event’s Rate is set to 1.5, the figure shows the arrival times generated by the event. The inter-arrival time of this event is distributed exponentially with mean 1/1.5 = 0.67:

To add a rate triggered event

1. Drag the Event element from the Agent palette onto the diagram of agent.
2. Once the event is created, you can specify its name in the text line editor opened on the right of the element in the graphical editor. When finished, press Enter and go to the Properties view.
3. Choose Rate from the Trigger type drop-down list.
4. Specify the rate in the Rate edit box below.
5. Specify the event’s action in the Action property. There you can write Java code to be executed on the event occurrence. Probably it would be more convenient to define this code as a function and just place the function call here.

The event’s rate can change dynamically at the model runtime, e.g. as a result of changing value of the parameter specified as the Rate. If the rate changes (and new rate is not equal to the current one), the event occurrence gets re-scheduled, i.e. the currently scheduled event is canceled and the next occurrence is scheduled according to the new Rate. If the new rate value equals zero or is negative, the currently scheduled event is canceled and new event will not be scheduled until you change the rate to a positive value and call the event’s restart() function afterwards.

Such changes may only be noticed when something changes in the agent:

• when any event occurs in this agent, e.g. a transition is taken, some another event occurs, parameter's On change action is executed, a message is received by one of agent's port, etc.
• when the user explicitly calls the function onChange() of the agent

You can control the rate triggered event programmatically via its API.

Controlling events

Function	Description
boolean isActive()	Returns true, if the event is currently scheduled, false otherwise.
void reset()	Cancels the currently scheduled event, if any. The cyclic execution would not resume until restart() is called.
void restart()	Cancels the currently scheduled event, if any, and schedules the next occurrence according to the Rate.
void onChange()	Should be called when something changes in the object (and probably the rate changes). Re-schedules the event with re-calculated rate.
double getRest()	Returns the time remaining before the scheduled occurrence of the event, in model time units. If the event is not scheduled, the function returns infinity.
double getRest(TimeUnits units)	Returns the time remaining before the scheduled occurrence of the event, in given time units. If the event is not scheduled, the function returns infinity. units - time unit constant Example: event.getRest(MINUTE) will return the remaining time in minutes.

If you want to monitor a certain condition and execute an action when this condition becomes true - use condition triggered event.

To add a condition triggered event

1. Drag the Event element from the Agent page of the Palette view onto the graphical diagram of agent.
2. Once the event is created, you can specify its name in the text line editor opened on the right of the element in the graphical editor. When finished, press Enter and go to the Properties view.
3. Choose Condition from the Trigger type drop-down list.
4. Specify the boolean condition in the Condition edit box. The event will occur when this condition will become true for the first time.
5. Specify the event’s action in the Action section. There you can write Java code to be executed on the event occurrence. Probably it would be more convenient to define this code as a function and just place the function call here.

By default condition triggered event occurs only once, when the specified boolean condition becomes true for the first time. Once occurred, the event does not monitor its condition anymore. Such behavior is implemented to prevent simulation loops, when the condition stays true, and the event's action code is executed again and again infinitely often.

However, in some cases you may need to continue monitoring the specified condition to detect when it will be met again.

If you want your event to continue monitoring the condition after the event has occurred once, end the Action of this event with the code string event.restart();

Condition triggered event occurs when the specified Boolean condition is true. If the condition is initially true, the event occurs immediately. Otherwise, it becomes enabled as soon as the expression becomes true.

It is important to understand, when an event's condition is checked by the model.

• If the agent has continuously changing variables, the numeric engine constantly monitors the condition, i.e. the condition is checked on every step of the numeric equation solver. This is done because the condition may become true as a result of equation solving, as a condition may contain variables changing continuously according to a set of differential and algebraic equations. When the condition becomes true, AnyLogic determines the switch point – the moment when the expression becomes true – with the accuracy set by the user.
• In purely discrete models the condition is tested when something changes in the agent:
  • when any event occurs in this agent, e.g. a transition is taken, some another event occurs, parameter's On change action is executed, a message is received by one of agent's port, etc.
  • when the user explicitly calls the function onChange() of the agent
  If something changes in embedded agent, condition is not checked!

  If you need to check conditions in embedded agents or populations, you can establish periodic checking of those conditions by doing the following. Set the Enable steps option in the Space and network section of the properties of the upper level agent where these agents reside. Add onChange(); code in the On step action (in the Agent actions properties section) of the agent where you want the conditions to be checked with certain frequency. This is a more efficient solution than having a cyclic event calling onStep() in each embedded agent.

When specifying a condition, you should keep in mind the so-called sensitivity problem. Let the event wait for the boolean condition x>=5, and let x changes continuously in time as shown in the figure below:

Sensitivity problem

As the numeric equation solver works by steps, it may happen that x will exceed the value 5 and get back in between the two steps. In this case the change event will not be detected. You should be aware of such situations when modeling systems where such error might be critical. If you encounter such a problem, you should make numerical method accuracies smaller.

You can control the condition triggered event programmatically via its API

Controlling events

Function	Description
void reset()	Cancels the currently scheduled event, if any. Stops waiting on the condition, (this can be later on resumed by calling restart()).
void restart()	Resumes waiting on the condition. Can be called in the event action or when event is inactive.

How can we improve this article?

Send