Debug Simulation Using Signal Breakpoints
This example shows how to:
Pause simulation at a specified time.
View signal values in the block diagram using port value labels.
Pause simulation at points of interest using signal breakpoints.
Step through a time step block by block.
View the execution order in the block diagram.
You can also step through a simulation from the beginning. For an example that shows how to step a simulation from the start and configure options for stepping through time steps and stepping back, see Step Through Simulation.
Open and Configure Model
Open the model vdp
, which implements the Van der Pol equation.
For more information about the model, see Van der Pol Oscillator.
openExample("simulink_general/VanDerPolOscillatorExample",... supportingFile="vdp")
You might run several simulations while analyzing and debugging your model. To save time by compiling the model only before the first simulation, enable fast restart. In the Simulink® Toolstrip, on the Simulation tab, click Fast Restart.
Specify Time to Pause Simulation
Suppose you know you need to analyze the behavior of your model around a certain
time in the simulation. You can run the simulation without interruption up to the
time you specify as the Pause Time. For this example, specify a
pause time of 2
seconds.
In the Simulink Toolstrip, on the Debug tab, in the
Breakpoints section, specify the Pause
Time as 2
. Then, to start the simulation, click
Run.
Because this is the first simulation, the model compiles before starting the
simulation. Then, the simulation pauses after the major time hit that happens at a
simulation time of 2.079
seconds. The status bar at the bottom of
the Simulink Editor displays the current simulation time. Some solvers perform
calculations to determine the time of the next major time hit before the point in
the simulation loop where the simulation pauses when you click Step
Forward. In this case, the solver is ahead in simulation time
relative to the block diagram. The asterisk on the simulation time indicates that
the solver has moved ahead in simulation time.
When you specify a pause time, the simulation does not necessarily pause at that exact time. The solver determines the time steps the simulation takes, and the simulation might not have a major time hit at the exact time you specify. Instead, the simulation pauses at the end the first major time hit that occurs at or after the time that you specify.
View Signal Values in Block Diagram
Both before and during simulation, you can add and remove port value labels to view signal values for each time step in the block diagram. You can add and remove port value labels for individual signals and for a selection of multiple signals.
For this example, add port value labels for all signals. Click an empty area in
the upper left of the canvas and drag to select everything in the block diagram.
Then, on the Debug tab, in the Tools
section, in the Port Values button group, click Show port value
label on selected signal . The port value labels show no data
yet
until the first forward step in simulation after you add the port
value labels.
Step Through Time Steps
While paused in simulation due to the pause time, you can use the Step Forward and Step Back buttons to step the simulation through major time steps. Before you can step back, you must enable stepping back. You can also configure the number of major time steps to advance the simulation each time you click Step Forward or Step Back. For more information, see Step Through Simulation.
Click Step Forward. The simulation advances forward by one major time step. The port value labels update to display the signal values from the time step.
You can continue advancing the simulation by clicking Step Forward. As the simulation progresses, you can observe the signal values using the port value labels and the Scope block in the model.
Set Breakpoint to Pause Simulation
You can use a signal breakpoint to pause the simulation each time a signal value satisfies the specified condition. When you use signal breakpoints, by default, the simulation pauses within the time step as soon as the condition is met, just after the block that produces the signal runs its output method to update the signal value.
You can control whether the simulation pauses within the time step when the condition is met or at the end of the time step in which the condition is met in the Breakpoints List. When you clear Pause within time step in the Breakpoints List, the simulation pauses at the end of the time step in which the condition is met. For more information, see Breakpoints List.
Suppose you want to investigate the behavior of the model when the value of the
signal x1
is close to zero. Specify the condition for the
breakpoint as > 0
. You could also configure the condition using
the equal (=
) relational operator. However, in that case, the
breakpoint pauses the simulation only when the signal has exactly that value. The
solver might choose time steps where the signal value is close to zero but not
exactly zero. The signal breakpoint with the condition > 0
pauses
the simulation in the time step just after the signal value passes through
zero.
To set the signal breakpoint:
Select the signal
x1
.On the Debug tab, in the Breakpoints section, click Add Breakpoint.
In the Add Breakpoint menu, select a relational operator to define the condition for the signal breakpoint. For this example, select greater than
>
.Specify the value for the breakpoint condition as
0
so that the simulation pauses when the value of the signalx1
becomes greater than zero.Click OK.
A red circle on the line for the signal x1
indicates that the
signal has an enabled breakpoint.
By default, during simulation, clicking a signal line adds or removes the port
value label for the line. To add the port value label for the signal
x1
, click the signal line again. The port value label
displays no data yet
because when you remove a port value label,
the software does not retain a history of signal values. The port value label
updates to display the signal value the next time the simulation advances
forward.
To advance the simulation until the breakpoint is hit, click
Continue. The simulation pauses when the signal value
becomes greater than zero. The port value label for the signal x1
shows the signal value that satisfied the breakpoint condition. The breakpoint icon
has a red arrow on it that indicates that the breakpoint caused the simulation to
pause. The block that produces the signal is highlighted green to indicate where the
simulation is paused within the time step.
The left side of the status bar provides a detailed simulation status that indicates where the simulation is paused.
When the simulation is paused on a breakpoint, you can open the Breakpoints List by clicking Open Breakpoints List near the middle of the status bar.
The green highlight in the Breakpoints List indicates that the simulation is paused on the breakpoint.
Step Block by Block
When the simulation is paused within a time step, the Step Over, Step In, and Step Out buttons become active, allowing you to step through the time step block by block. To step the simulation to the next block, click Step Over.
The simulation pauses just before executing the output method for the Outport block. The breakpoint no longer has the green arrow on it.
The next time you click Step Over, the simulation pauses just
before executing the output method for the Integrator block named
x2
. When you click Step Over once more,
the Integrator block named x2
executes its output
method, the port value label updates to display the new signal value, and the
simulation pauses just before executing the output method for the second
Outport block.
While paused within a time step, you can use some functions from the Simulink debugging programmatic interface to get additional information about
the simulation. For example, you could use the probe
function
to view information about a specified block. Port value labels display only signal
values that result from blocks running their output methods in a major time step.
When you use functions from the Simulink debugging programmatic interface, the values displayed might be
different because the functions show results from minor time steps as well.
As you continue to click Step Over to step through the time step, after the Scope block executes its output method, the simulation pauses with no blocks in the block diagram highlighted green. The status string on the left side of the status bar indicates that the simulation is paused on a hidden block. Because the block is hidden, no green highlight appears in the model. In this case, the hidden block is part of the logging implementation for the Outport blocks.
You can continue stepping the simulation one block at a time through multiple time steps. If you click Step Forward or Step Back, only the Step Over button remains enabled to allow you to resume stepping within a time step, block by block.
Before R2024a: If you click Step Forward or Step Back, the simulation pauses between time steps, and the Step Over, Step In, and Step Out buttons are disabled. The Step Over, Step In, and Step Out buttons are enabled again when the simulation pauses on a breakpoint.
View Execution Order
When you step the simulation block by block, the blocks do not execute based on the layout of the block diagram. At the start of the simulation, the software determines the execution order for all tasks and blocks in the model. In each time step, the tasks and blocks execute according to the execution order.
To understand the order in which the blocks execute as you step, you can view the execution order in the block diagram. To display the execution order, on the Debug tab, in the Diagnostics section, click Information Overlays. Then, under Blocks, click Execution Order. The Execution Order viewer opens on the right of the Simulink Editor with the current task selected. The Execution Order viewer highlights and annotates the model to indicate the blocks involved in the current task and their order of execution.
When you first open the Execution Order viewer, the execution order highlighting
obscures the green debugging highlight that indicates where the simulation is paused
within the time step. After you advance the simulation, the green debugging
highlight overlays the execution order highlighting. For example, click
Step Over. The simulation pauses on the
Integrator block named x1
, and the green
highlight around the block overlays the highlighting from the Execution Order
viewer. The Execution Order viewer also highlights the row for the
Integrator block named x1
in the
Execution Order Block List.
You can continue to step through the simulation with the execution order highlighting visible in the block diagram, or you can clear the execution order highlighting to focus on other aspects of debugging. To clear the execution order highlighting, in the Execution Order viewer, click Clear Highlighting . To view the execution order again in the block diagram, in the Execution Order viewer, select the task for which you want to view the execution order.
Before R2024a: The execution order highlighting overlays the green debugging highlight that indicates where the simulation is paused, even after you advance the simulation.
End Simulation Debugging Session
When you are done analyzing and debugging your model, you can end the simulation debugging session in one of several ways, depending on what you plan to do next.
To continue the simulation from the current time point and retain the set of breakpoints configured in the model, disable all breakpoints.
To open the Breakpoints List, on the Debug tab, click Breakpoints List.
In the Breakpoints List, use the check boxes in the Enable column or the Enable or disable all breakpoints button to disable all the breakpoints.
To resume the simulation, click Continue.
To continue the simulation from the current time point without retaining breakpoints, remove all breakpoints from the model.
To clear all breakpoints in the model, on the Debug tab, click the Add Breakpoint button arrow and select Clear All Breakpoints.
To resume simulation, click Continue.
To stop the simulation at the current time point, in the Simulink Toolstrip, on the Debug tab, click Stop.
See Also
Simulation Stepping Options | Breakpoints List