A transition denotes a switch from one state to another. A transition indicates that if the specified trigger event occurs and the specified guard condition is true, the statechart switches from one state to another and performs the specified action. When this occurs, we say that the transition is taken.

The starting point of a transition lies on the border of the transition’s source state. The end point of a transition lies on the border of the transition’s destination state. A transition may freely cross simple state and composite state borders. If the source of a transition lies either on or inside a state, and the destination of that transition lies outside of the state, then that state is considered exited by the transition. If such a transition is taken, the exit action of the exited state is executed. If the source of a transition lies outside a state, and the destination of that transition lies either on or inside the state, then that state is considered entered by the transition. If such a transition is taken, the entry action of the entered state is executed. In case a part of a transition lies inside a state, but both source and destination are outside the state, this state is considered neither entered nor exited.

There is a special type of transition called internal transition. An internal transition lies inside a state, and both start and end points of the transition lie on the border of this state. Since an internal transition does not exit the enclosing state, neither exit nor entry actions are executed when the transition is taken. Moreover, the current simple state within the state is not exited too. Therefore, the internal transition is very useful for implementing simple background jobs, which should not interrupt the main activity of the composite state.

Transitions

Demo model: Cell Phone User Statechart with Internal Transitions Open the model page in AnyLogic Cloud. There you can run the model or download it (by clicking Model source files).

To draw a transition

1. Drag the Transition element from the Statechart palette onto the graphical diagram of agent (so that the starting point of the transition lies on a border of a state or pseudo state). Then drag the ending point of the transition onto a border of another state.
2. In some cases (especially when you want to draw a transition containing turning point(s)) it is more convenient to use drawing mode. To activate it, double-click the Transition element in the palette. Its icon will turn into . Now you can draw a transition in the following way: first, click in the place of the diagram, where the starting point of the transition should be located, then subsequently click the points where the transition should turn and finally double-click the ending point of the transition. As the result, the transition of the required form will be drawn at once.

General

Name – The name of the transition.

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

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

Triggered by – Choose the type of event that triggers the transition.

• Timeout – the transition is triggered after the specified timeout elapses.
• Rate - the transition is triggered with the specified rate.
• Condition - the transition is triggered when the specified boolean condition is true.
• Message - the transition is triggered when a message arrives to the connected port.
• Agent arrival - the transition is triggered when an agent (whose behavior is defined by this particular statechart) reaches its destination.

Timeout – [Visible if the transition is Triggered by: Timeout] The timeout triggering the transition. The transition triggering will be enabled after the specified timeout will elapse.

Rate – [Visible if the transition is Triggered by: Rate] The rate triggering the transition. The transition is executed with the timeout distributed exponentially with the parameter Rate (counted from the moment the statechart came to the transition's source state). I.e. if the rate is 5, the transition will be executed on average 5 times per time unit.

Condition – [Visible if the transition is Triggered by: Condition] The condition triggering the transition. The transition triggering will be enabled when the specified Boolean expression is true.

Message type – [Visible if the transition is Triggered by: Message] Specify the type of the message that will trigger this transition. You can choose one of the most-used types (int, double, boolean, String) using the corresponding option to the right. However, if your messages are of some other Java class, choose the Other option and type the required class name in the Class name field below.

Fire transition – [Visible if the transition is Triggered by: Message] Here you can impose additional condition that should be satisfied to allow transition triggering.

• Unconditionally – Choose this option if you do not want to perform message type checking.
• On particular message - If selected, only messages equal to the text string specified in the Message edit box below will trigger the transition.
• If expression is true - In the Expression field below, you can define a sophisticated message contents checking. The just received message can be accessed here as msg variable. If the specified expression returns true, the transition is triggered.

Action – Here you can write Java code to be executed when the transition is taken.

Guard – Boolean expression that allows (if returns true) or prohibits (if returns false) the transition. If the guard expression is not specified, true is assumed.

Transitions exiting branch states have the following properties, slightly different from other transitions properties:

• Condition – If selected, this transition will be triggered when the boolean condition specified in the Condition field below will be true.
• Default (is taken if all other conditions are false) – If selected,the transition is the default branch exit and will be taken if conditions defined for all other transitions exiting the branch state are false. If all outgoing transitions are closed and there is no default exit from a branch, a runtime error is issued.

When a statechart enters a simple state, the triggers of all outgoing transitions (including the transitions outgoing all composite states containing the simple state) are collected and the statechart begins to wait for any of them to occur. When a trigger event occurs, the guard of the corresponding transition is evaluated. If the guard is true, then the transition may be taken (we say "may be" because there may be alternative simultaneous events at AnyLogic simulation engine, which may reset the trigger). This algorithm of guard evaluation is called "guards-after-triggers".

If several triggers are signaled at the same time, and the corresponding guards are true, the transition to be taken can be chosen randomly or deterministically.

Transition can be triggered as a result of various types of events occurred, listed in the table below. You specify the trigger type in the Triggered by property of a transition.

Trigger type	Primary use	Transition fires
Timeout	Timeout: change state if other awaited events do not occur within the specified time interval. Delay: stay in a state for a given time, then leave.	After a specified time interval counted from the moment the statechart enters the direct "source" state of the transition (i.e. the state on whose boundary the transition start point is located). The timeout expression is calculated one time when the statechart enters that state. The expression can be stochastic as well as deterministic.
Rate	Sporadic state change with a known mean time. In agent based models used to represent sporadic decisions made by an agent under a certain, possibly variable, influence (purchase decisions, adoption of ideas, etc.).	Same as timeout, but the time interval is drawn from an exponential distribution parameterized with the given rate. For example, if the rate is 0.2 the timeouts will have mean values of 1/0.2 = 5 time units. If a change occurs in the agent while the rate transition is active (namely, if onChange() function is called), the rate expression is re-evaluated and, if it gives a new result, the transition is rescheduled using a new exponential distribution.
Condition	Monitor a condition and react when it becomes true. For example: buy if the stock price falls below a certain threshold; launch a missile if the aircraft is closer than 5 miles, etc.	Once a given condition becomes true. The condition is an arbitrary boolean expression and may depend on the states of any agents in the whole model with continuous as well as discrete dynamics. In most cases you can assume the condition is constantly monitored while the transition is active.
Message	React to messages received by the statechart or by the agent from outside. The messages can model communication between people or organizations, commands given to a machine, physical products, electronic messages, etc. The ways of sending a message to a statechart are described in Communication between agents.	Upon reception of a message that matches the template specified in the transition properties.
Agent arrival	React to agent arrival to the specified destination. Can be used in moving agents.	When the agent arrives at the destination point (assuming its movement was initiated by calling moveTo() function).

The transition becomes enabled after the specified amount of time (the timeout) elapses, since the statechart comes to the source state of the transition. Such transition may be used to model delays and, combined with alternative transitions, timeouts.

Timeout triggered transition is depicted by the icon .

Demo model: Statechart for Laptop Running on Battery Open the model page in AnyLogic Cloud. There you can run the model or download it (by clicking Model source files).

To define a timeout triggered transition

1. Select the transition in the graphical editor.
2. In the Properties view, choose Timeout from the Triggered by drop-down list.
3. Specify the timeout in the Timeout edit box below.

Working with transition programmatically

Function	Description
boolean isActive()	Returns true, if the transition is currently scheduled, false otherwise.
double getRest()	Returns the time remaining before the scheduled occurrence of the transition, in model time units. If the transition is not scheduled, the function returns infinity.
double getRest(TimeUnits units)	Returns the time remaining before the scheduled occurrence of the transition, in given time units. If the transition is not scheduled, the function returns infinity. units - time unit constant Example: transition.getRest(MINUTE) will return the remaining time in minutes.

Statechart transition with trigger of type rate. A rate is a form of updatable exponential timeout. Such transition is executed with the timeout distributed exponentially with the parameter rate (counted from the moment the statechart came to the transition's source state), i.e. if the rate is 5, the transition will be executed on average 5 times per time unit. Rate triggered transition is depicted by the icon .

Demo model: Statechart for Generic Resource Open the model page in AnyLogic Cloud. There you can run the model or download it (by clicking Model source files).

To define a rate triggered transition

1. Select the transition in the graphical editor.
2. In the Properties view, choose Rate from the Triggered by drop-down list.
3. Specify the rate value in the Rate edit box below.

If the rate changes dynamically, the timeout gets re-evaluated; such changes may only be noticed by transition if onChange() is called for the agent. If the new rate value is negative, the error is thrown.

Working with transition programmatically

Function	Description
boolean isActive()	Returns true, if the transition is currently scheduled, false otherwise.
double getRest()	Returns the time remaining before the scheduled occurrence of the transition, in model time units. If the transition is not scheduled, the function returns infinity.
double getRest(TimeUnits units)	Returns the time remaining before the scheduled occurrence of the transition, in given time units. If the transition is not scheduled, the function returns infinity. units - time unit constant Example: transition.getRest(MINUTE) will return the remaining time in minutes.

The transition is executed when the condition becomes true. If the agent has continuously changing variables, the numeric engine constantly monitors the condition. In purely discrete models the condition is tested when something changes in the agent, i.e. when onChange() is called.

Condition triggered transition is depicted by the icon .

You can find the statechart shown in the figure above in the Ship agent type in the following demo model.

Demo model: Container Line Open the model page in AnyLogic Cloud. There you can run the model or download it (by clicking Model source files).

To define a condition triggered transition

1. Select the transition in the graphical editor or in the Projects view.
2. In the Properties view, choose Condition from the Triggered by drop-down list.
3. Specify the condition in the Condition edit box below.

A transition with such a trigger is enabled when the specified Boolean expression is true. If by the time the statechart comes to the source state of such transition the expression is true already, the transition becomes enabled immediately. Otherwise, it becomes enabled as soon as the expression becomes true – e.g., as a result of equation solving, as a change event 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.

It is important to understand, when the transition'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.
• 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 object, 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 change event, you should keep in mind the so-called sensitivity problem. Let the transition wait for the Boolean expression 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.

Such transition is executed when the statechart receives a message (an instance of an arbitrary Java class, or primitive type value) that conforms with the defined message descriptor. Arrival triggered transition is depicted by the icon .

Demo model: Bass Diffusion Agent Based Open the model page in AnyLogic Cloud. There you can run the model or download it (by clicking Model source files).

You send messages from one agent to other(s) by calling one of agent’s send() functions, see the functions list in Communication between agents.

When a statechart receives a message:

• If there is one or several transitions outgoing from the current simple state or any of its container states, the trigger of which matches the first event in the queue, such transitions become enabled, i.e. one of it is taken depending on guards. The message is immediately consumed.
• Otherwise, the message is discarded.

You can perform message checking and discard messages not matching the defined conditions. The match can be determined using only message class and/or the message object also.

• You can define message type checking to allow triggering transition only by messages of some particular message type.
• Moreover, you can filter messages by contents. You can define a message descriptor and accept only messages matching this descriptor. Event descriptor is an object, which is compared with a received message to decide if a transition should be triggered – a filter for message events. Or you can define some boolean condition operating with message contents and check it on each message reception. Transition will be triggered only when this condition is true. Since you can refer to the message contents in this expression, this way you can implement sophisticated message contents checking.

To define a message triggered transition

1. Select the transition in the graphical editor.
2. In the Properties view, choose Message from the Triggered by drop-down list.
3. If you want to perform message type checking, specify the message type allowed to trigger the transition using Message type parameter. To define some Java class, select the Other button and enter the class name in the edit box on the right. In this case transition will be triggered only by messages of this particular type or Java class.
4. Otherwise, if you do not wish to perform message type checking, leave the default settings when Other button is selected and Object class is specified.
5. Now define the message contents checking conditions using the Fire transition group of buttons.
6. In case you do not wish to perform message contents checking, simply choose the Unconditionally option.
7. If you want to define the message descriptor and accept only messages with the same contents, choose the On particular message option and specify the descriptor value in the edit box Message below. It works in the following way: when a message is received at a statechart, AnyLogic calls the function equals() of a descriptor, giving a reference to the message as a parameter. The function equals() may use just message type information, or may look at message parameters. If it returns true, then the event matches the descriptor and the transition should be taken. false means no match. Possible message descriptors are "STOP!" for a message of type String, or 5.0 for a message of type Double.
8. Otherwise, if you want to define a sophisticated message contents checking using a condition, choose the If expression is true option. Enter the expression in the edit box below. Here you can access the just received message as msg variable.
9. Enter the transition's guard expression in the Guard edit box.
10. Enter the transition's action code in the Action edit box.

Sometimes you may need to place incoming messages into the statechart queue. The message queue is necessary because message may arrive at those moments of time in which the statechart cannot react to events (e.g. when a transition is executed).

The queue is processed by a statechart every time something occurs to the statechart or fireEvent() function of the statechart. It iteratively checks all message in the queue starting from the "oldest" one according to the following algorithm:

• If there is one or several transitions outgoing the current simple state or any of its container states, the trigger of which matches the currently checked message, such transitions become enabled, i.e. one of it is taken depending on guards. This message and all preceding messages in the queue are discarded. The next message in the queue is processed.
• If there are no such transitions, the next message is processed.

A statechart can make several consequent steps processing several messages from the queue (these steps take zero model time).

Such kind of a transition is triggered when an agent (whose behavior is defined by this particular statechart) reaches its destination.

Transition triggers if the agent lives in continuous or GIS space and its movement was initiated by calling one of agent's moveTo() or similar movement functions or with MoveTo block of Process Modeling Library.

Arrival triggered transition is depicted by the icon .

You can find the statechart shown in the figure above in the Truck agent type in the following demo model.

Demo model: Statechart for Delivery Truck Open the model page in AnyLogic Cloud. There you can run the model or download it (by clicking Model source files).

To define arrival triggered transition

1. Select the transition in the graphical editor or in the Projects view.
2. In the Properties view, choose Agent arrival from the Triggered by drop-down list.
3. Optionally type Java code that should be executed on transition occurrence in its Action property field.

How can we improve this article?

Send