Simulating statecharts

Simulating a statechart model means to execute it, raise events manually, have time-based and other events being triggered automatically, and observe the model’s behavior.

You can run multiple state machines in parallel and even multiple instances of the same state machine.

An introduction to simulation is given in section "Simulating the light switch model".

Starting a simulation

You have several options to start a statechart simulation.

Using the statechart model file context menu

The most direct way is to start the simulation based on the statechart model file.

  1. In the project explorer view, right-click on the statechart model file. The context menu opens.
  2. In the context menu, select Run As → Statechart Simulation, see figure "Selecting Run As → Statechart Simulation in the context menu" .

Selecting "Run As → Statechart Simulation" in the context menu

Selecting Run As → Statechart Simulation in the context menu

Repeating the last simulation

In order to re-run the simulation you have most recently executed, simply

  • press [Ctrl+F11] on the keyboard

or

  • select Run → Run in the main menu.

To be exact, this operation does not necessarily re-run the last simulation, but rather the last executed launch. So if, for example, you first run a statechart simulation followed by running a Java program, then upon pressing [Ctrl+F11] that Java program is executed once again, not the statechart simulation.

Repeating an earlier simulation

Let’s consider a scenario where you want to execute a simulation that you have run before, but not as the most recently executed launch. So you cannot use the procedure described in section "Repeating the last simulation".

However, as long as you haven’t launched too many other programs in between, chances are good to find your simulation in the history.

Try the following:

  1. In the main menu, open the Run menu and move your mouse pointer over the Run History entry.
  2. A submenu attached to the Run History menu entry opens, containing the most recently executed launches. Check whether the simulation you want to execute is available in the submenu. If it is, select it to start the simulation.

Creating and executing a launch configuration

When a statechart is simulated for the first time, a launch configuration is automatically created. A launch configuration describes the parameters used for a particular launch. In case of a statechart simulation, it describes which statechart is to be simulated and the simulation mode (event-driven or cycle-based). For details on how to create and modify a launch configuration, see section "Configuring a simulation".

To execute an existing launch configuration, proceed as follows:

  1. In the main menu, select Run → Run Configurations…. The Run Configurations dialog appears.
  2. The list on the left-hand side of the Run Configurations dialog displays all available launch configurations. Select the launch configuration you want to execute.
  3. Click on Run to execute the launch configuration.

The SC Simulation perspective

The SC Simulation perspective provides selected views that are most useful when running a statechart simulation.

Engaging the SC Simulation perspective

When a simulation starts, the perspective usually changes to the SC Simulation perspective. If this doesn’t happen, you can manually engage the SC Simulation perspective as follows:

  • In the main menu, select Window → Perspective → Open Perspective → SC Simulation.

Alternatively, you can do the following:

  • In the main menu, select Window → Perspective → Open Perspective → Other…. The Open Perspective dialog appears.
  • In the Open Perspective dialog, select SC Simulation.
  • Click on Okay. The SC Simulation perspective opens.

Views contained in the SC Simulation perspective

By default, the SC Simulation perspective shows the following views:

  • Project Explorer (left): This view displays your workspace and projects, folders, and files contained therein. You can also use the Project Explorer to inspect the internal structure of your statechart models.
  • Debug (top middle): This view is showing all state machine instances and allows to select one of them. YAKINDU Statechart Tools allow multiple executions of the same statechart as well as parallel executions of different statecharts at the same time.
  • Outline (right): This view is a bird’s eye view on the opened statechart. It also indicates the current viewport for better orientation in large models.
  • Simulation (right): This view shows the current state of all variables and events during a simulation. A detailed description is available in section "The Simulation view".
  • Breakpoints (right): This view shows a list of all breakpoints. You can use it for disabling, enabling, or removing breakpoints as well as for defining conditional breakpoints.
  • Snapshots (right): This view contains all snapshots with their respective names and timestamps.

Displaying simulation progress in the statechart editor

The SC Simulation perspective also includes the statechart editor. In a running simulation, the statechart editor highlights active states by coloring their backgrounds in red.

When a transition is taken, the transition arc leading from the source state to the target state flashes briefly in red. After that, the target state becomes active and changes its background color to red. The source state’s background color becomes normal again.

The "SC Simulation" perspective

The SC Simulation perspective

The Simulation view

The Simulation view is used to manually raise events and to inspect and modify variables of a running simulation. By default that view is located on the right-hand side of the SC Simulation perspective, see figure "Simulation view" for an example.

The Simulation view groups events and variables by their interfaces. The unnamed interface appears as default in the interface list. Click on the small triangle left from a interface’s name to show or hide the interface’s contents, i.e. events and variables.

Please note:

Depending on your screen resolution and font size settings, you might not be able to spot the Simulation view by its name, because the tab containing it is quite narrow and might not provide enough space for displaying the title. Hover over the tabs to reveal their respective titles in a popup window.

Figure "The SC Simulation perspective" is demonstrating this: The user has hovered the mouse pointer over a tab that is just displaying the starting letter ‚S’ of its title. However, a popup window right besides the pointer is showing the tab’s full title „Simulation”.


Simulation view – The actual "Simulation" view is the pane right from the statechart editor.

Simulation view – The actual Simulation view is the pane right from the statechart editor.

Controlling a simulation

  • To terminate the simulation, click on the Terminate button Symbol: Terminate or select Run → Terminate in the main menu.
  • To suspend the simulation, click on the Suspend button Symbol: Suspend or select Run → Suspend in the main menu.
  • To resume a suspended simulation, click on the Resume button Symbol: Resume or select Run → Resume in the main menu.
  • Use the Step Over button Symbol: Step Over or select Run → Step Over in the main menu to execute a single run-to-completion step.

Interacting with a simulation

You can interact with a running simulation by manually raising events and by inspecting and modifying variables. You can do so at any point in time, but in most cases you will do so while the simulation „sits idle” at its active state and waits for an event to trigger a transition.

Raising an event in the simulation

To raise an event, proceed as follows:

  1. In the Simulation view, click on the small triangle to open the interface containing the event, if needed.
  2. Click on the event to raise it for the next run-to-completion step.

Inspecting a variable

To inspect a variable’s value, proceed as follows:

  1. In the Simulation view, click on the small triangle to open the interface containing the variable, if needed.
  2. The variables contained in the interface are displayed.

Watch the displayed values change as the simulation progresses and actions in states or transitions are executed that modify the variables' contents.

Modifying a variable

To manually modify a variable’s value, proceed as follows:

  1. In the Simulation view, click on the small triangle to open the interface containing the variable, if needed.
  2. Double-click on the variable’s name. It is replaced by a text field containing the variable’s current value.
  3. Enter the variable’s new value and press [Enter]. The new value is assigned to the variable and replaces the former value.

Configuring a simulation

Section "Creating and executing a launch configuration" describes how to start an existing launch configuration.

The present section describes how to create and configure a new launch configuration for a statechart simulation.

  1. In the main menu, select Run → Run Configurations…. The Run Configurations dialog appears. The "Run Configurations" dialog
  2. In the Run Configurations dialog, right-click on Statechart Simulation and select New in the context menu. The "Run Configurations" dialog
    Alternatively, you can select Statechart Simulation and then click on the New symbol near the top-left corner of the dialog. The "Run Configurations" dialog
    However you do it, a new launch configuration is created and displayed in the main area of the Run Configurations dialog. The launch configuration’s Main tab is opened.
  3. Enter the launch configuration’s parameters as necessary:
    • In the Name text field, change the default name New_configuration to something sensible, e. g. Light switch.
    • In the Model file text field, enter the path to the statechart model you want to simulate. Click on the Search button to browse for statecharts.
    • If your model uses Java operations, specify the Java class implementing those operations in the Operation class text field. If you have multiple Java classes, specify them as a comma-separated list.
    • Specify the Execution type as being either cycle-based (default) or event-based. In a cycle-based execution, the simulation performs a run-to-completion step (RTC) in regular intervalls and processes the events that have occurred since the previous RTC. See the next field for the period of time between two consecutive RTCs. – In an event-based execution, the simulation performs an RTC each time an event occurs. Please note: In contrast to the statechart simulation any generated code does not necessarily conform to the event-based execution semantics.
    • If the execution type is cycle-based, specify the period of time between two RTCs in the Cycle time text field. If the execution type is event-based, this field is deactivated. The "Run Configurations" dialog

Please note:

Besides the Main tab described above, a statechart simulation launch configuration also has a tab named Common. This tab is a common standard to all types of launch configurations, and thus it is not documented here.

In addition to creating new launch configurations, you can also duplicate or delete launch configurations in the Run Configurations dialog. Right-click on a launch configuration and select Duplicate or Delete from the context menu.

Debugging with breakpoints and snapshots

Introduction

This advanced feature makes it possible to attach breakpoints to states and transitions. If a statechart simulation reaches a transition or a state with a breakpoint, it suspends execution of the simulation. A breakpoint can be amended with a condition in order to suspend the simulation only if the condition is fulfilled (true).

You can also create snapshots of your statechart simulation. A snapshot contains everything making up your state machine simulation at any point in time. It describes the state of the state machine, if you will. Snapshots can be saved and restored later in order to continue the simulation from that point on that is specified by the snapshot.

The light switch example

Throughout this chapter we will be using the light switch statechart as an example. It models a lamp which can be turned on and off and also supports various brightness values.

If you press the pressLightOn button, the lamp turns on at its lowest brightness value. If you operate pressLightOn repeatedly, each time the lamp becomes brighter until it reaches its maximum brightness. Pressing the pressLightOff button, immediately turns off the light completely. The brightness can only be raised as long as it hasn’t yet reached its maximum value of five. After that, the guard condition disallows to raise it any further.


The light switch sample statechart

The light switch sample statechart

Breakpoints

Breakpoints allow for automatically suspending the simulation when a certain element of the state machine is activated. Optionally, a halting condition can be specified to better control the behavior of a breakpoint. Breakpoints can be set on transitions or states. When a breakpoint is reached, the simulation pauses and the current state of variable values can be examined in the simulation view. It is possible to change values and to trigger events that will be raised when the simulation run is manually resumed.

Executing in debugging mode

To make use of breakpoints, the statechart simulation needs to be executed in debugging mode:

  1. Right-click on the statechart model. The context menu opens.
  2. Select Debug As→Statechart Simulation, see Figure "Starting a simulation in debugging mode".
  3. The statechart simulation starts in the debugging mode.


Starting a simulation in debugging mode

Starting a simulation in debugging mode

Setting a breakpoint

  1. Right-click on a state or transition. The context menu opens.
  2. Select Toggle Breakpoint from the context menu, see Figure "Setting a breakpoint".


Setting a breakpoint

Setting a breakpoint

States and transitions having a breakpoint attached are labeled with a Symbol: Breakpoint enabled symbol. Figure "Breakpoints on transition and state" shows an example.


Breakpoints on transition and state

Breakpoints on transition and state

Hitting a breakpoint

If the simulation runs into a state with a breakpoint, the state’s entry actions, if any, are executed. After that, execution of the state machine is suspended. The state is highlighted by a small green border.

Highlighting a suspended state

Highlighting a suspended state

If the simulation runs into a transition with a breakpoint, execution of the state machine is suspended. The transition is highlighted by drawing the transition arrow in green. The transition’s actions, if any, are executed when the state machine is resumed.

Highlighting a suspended transition

Highlighting a suspended transition

Continuing the simulation

In order to continue from a breakpoint, you have two options:

  • To continue execution, click the resume button Symbol: Resume or select Run → Resume in the main menu. The statechart simulation continues until the next breakpoint is hit or the simulation is terminated.
  • To execute the next run-cycle of the simulation only and then suspend again, click the step-over button Symbol: Step Over or select Run → Step Over in the main menu.

Using the breakpoints view

The breakpoints view shows a list of all breakpoints. The respective breakpoint name identifies the state or transition in question. See figure "Breakpoints view" for an example.

You can use the breakpoints view for disabling, enabling, and removing breakpoints as well as defining conditional breakpoints.


The "Breakpoints" view

The Breakpoints view

Enabling and disabling breakpoints

A breakpoint is either enabled or disabled.

  • An enabled breakpoint causes the statechart simulation to suspend when reaching it. In the statechart and in the breakpoints view, an enabled breakpoint is visualized by a filled light blue circle with a grey border: Symbol: Breakpoint enabled.
  • A disabled breakpoint is ignored by the statechart simulation. In the statechart and in the breakpoints view, a disabled breakpoint is visualized by a hollow circle with a grey border: Symbol: Breakpoint disabled.

Figure "Breakpoints view" is showing an enabled and a disabled breakpoint in the statechart editor and in the breakpoints view, respectively.

You can instruct the statechart simulation to skip all breakpoints by clicking at the Button [disengaged]: Skip all breakpoints button in the breakpoints view. The button will appear „pressed”, and while it is, the „skip breakpoints” functionality is engaged. That means, the simulation will not suspend at any breakpoint.

This is different from disabling all breakpoints, in that each breakpoint keeps its state of being enabled or disabled. Once you disengage the skip breakpoints functionality by clicking at the Button [engaged]: Skip all breakpoints button again, the simulation will suspend again at enabled breakpoints and will not suspend at disabled breakpoints.

Removing breakpoints

In order to remove some breakpoints, select these breakpoints in the breakpoints view, then click at the Button: Remove button. The selected breakpoints will be removed.

To remove all breakpoints, click at the Button: Remove all button

Conditional breakpoints

A conditional breakpoint has an associated condition and suspends the simulation only if

  • that condition is fulfilled (true) and
  • the breakpoint is enabled.

In order to attach a condition to a breakpoint, proceed as follows:

  • In the breakpoints view, select the breakpoint in question.
  • Check the Conditional checkbox, see figure "Breakpoints view" in the lower right area. The associated text field becomes writable.

Enter the condition into the text field. Like in the statechart editor, a content assist is available when pressing [Ctrl+Space]. The expression is validated automatically. In the example shown in figure "Breakpoints view" the transition suspends the simulation only if the variable brightness has a value of 4.

Debugging a statechart

Changing variable values

In the suspended status of a statechart simulation you can change variable values using the simulation view. When continuing execution – see section Continuing the simulation – you can observe how your state machine behaves with those modified values.

Raising multiple events simultaneously

If you click on an event’s name in the simulation view to raise that event in normal simulation, i.e. while execution isn’t suspended, the state machine immediately processes that event and takes the corresponding transition, if any.

However, while the simulation is suspended, you can raise multiple events, without instant execution. Once execution resumes, both events are handled at the same time, or, to be more exact, in the same run-to-completion step (RTS).

Consider for example, you want to press the "light on" and "light off" buttons at the same time and observe what happens. Figure "Raising multiple events simultaneously" is showing the scenario:


Raising multiple events simultaneously [1]

Raising multiple events simultaneously [1]

  • The simulation has encountered a breakpoint at the LightOn state and has been suspended there.
  • The simulation view shows the LightOn and the LightOff events. Both events are labeled with a Symbol: Event [not raised] symbol, meaning the respective event is not raised.


Raising multiple events simultaneously [2]

Raising multiple events simultaneously [2]

  • Clicking at an event raises it and adds a blue triangle to the event symbol: Symbol: Event [raised]. Since the simulation remains suspended, the user can raise multiple events.

Both events are raised and will be handled by the state machine during the next run-to-completion step. The latter will be performed as soon as the user clicks on the step-over button Symbol: Step Over or the resume button Symbol: Resume.

Please note: While the execution is still suspended, you can „unraise” an already raised event by clicking at the event symbol Symbol: Event [raised] a second time. The blue triangle will disappear, and upon continuation of the simulation the event will not be handled.

Transition priorities

It is important to understand that there is not queue of events. That is, in case several events occur simultaneously, the state machine consults the active state’s transitions priorities in the order that is specified in the corresponding property, see figure "Transition priorities". You can change the transitions priorities by selecting a transition and moving it up or down by clicking at the respective button.

The first transition whose condition is fulfilled will be executed. All remaining events are quashed.


Transition priorities

Transition priorities

Snapshots

The snapshot feature allows to store and restore the state of a simulation run. A snapshot comprises all active states of the state machine as well as all variable values at the time of snapshot creation.

This feature is especially useful when testing complex state machines in which a number of steps need to be taken before reaching a desired situation. Using snapshots, you can store this desired situation once and simply restore it again without repeating all the steps to reach it. Depending on the complexity of the usecase, this can be a huge time-saver.

Creating a snapshot

To create a snapshot of the current statechart simulation, proceed as follows:

  1. Change to Snapshots view.
  2. Click at the camera button Button: Camera in the view’s toolbar.
  3. The snapshot is taken and appears in the snapshot list. It is labeled as „Snapshot” and tagged with the current timestamp. See figure "A freshly taken snapshot".


A freshly taken snapshot

A freshly taken snapshot

The snapshots view

The snapshots view consists of two parts.

  • The snapshot list contains all snapshots with their respective names and timestamps.
  • The snapshot details part displays the contents of the snapshot. It contains two different views which can be toggled via the toolbar buttons:
    • Button: Show all variable values: shows all variable values
    • Button: Show image overview: shows an image of the state machine with highlighted active elements


Inspecting snapshot details: variables overview [left], image overview [right]

Inspecting snapshot details: variables overview [left], image overview [right]

Restoring a snapshot

To restore a snapshot for execution, proceed as follows:

  1. Select the snapshot to be restored.
  2. Click at the restore button Button: Restore snapshot.
  3. The snapshot is restored as an additional executing state machine instance.

Please note: When the semantics of the underlying state machine have been changed, it might not be possible to restore a snapshot, e.g. when the active state has been deleted.

Naming a snapshot

The label of a snapshot can be changed as follows:

  1. Click at its label. The label becomes an editable field.
  2. Enter the new snapshot name and press [Return] or click anywhere outside the editable field.

Deleting a snapshot

  • To delete one or more snapshots, select the snapshots to be deleted, then click at the remove button Button: Remove.
  • To delete all snapshots, click at the remove all button Button: Remove all.