Condition Triggered Event

If you want to monitor a certain condition and execute an action when this condition becomes true - use 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.

Properties

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 becomes true.

Mode – [Visible if Trigger type is 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 (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).
Please note that 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).
Please note that 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 this event was created at..

Timeout – [Visible if Trigger type is Timeout and Mode is 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 is Timeout and Mode is Occurs once or Cyclic] If selected, the event will occur at the specified model time.

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

Occurrence time (absolute) – [Visible if Trigger type is Timeout, Mode is 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 is Timeout, Mode is 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 is Timeout, Mode is 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 is Timeout and Mode is Cyclic] The recurrence time of the cyclic event.

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

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

Log to database – If selected, information on all event occurrences will be logged into the model execution log events_log.

Action

Java code to be executed on event occurrence.

How to continue monitoring a condition after it has been already met?

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

To eliminate immediate triggering of this event, please do not forget to set the condition, that triggers this event, to false (do it in the same Action field just before restarting the event).

When a condition of an event is checked?

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.
  Please note that if something changes in embedded object, condition is not checked!

Sensitivity problem

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.

Controlling events manually

You can control the condition triggered event programmatically via its API:

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.

Related topics

Event

Timeout triggered event

Rate triggered event

Dynamic event

API reference: EventCondition class