Main Content

Debug Simulation of Iterator Subsystem

Iterator subsystems repeat the execution of the algorithm modeled inside the subsystem one or more times within a simulation time step. To analyze or debug the algorithm inside an iterator subsystem, you need to pause within a major time step when the iterator subsystem executes and step the model execution by a more granular interval than major time steps.

This example shows how to analyze a simple summing algorithm implemented using a while-iterator subsystem.

Open Example Model

The model IterateSum uses a while-iterator subsystem to implement an iterative summing algorithm. The while-iterator subsystem has two inputs: a sine wave signal and a pulse signal. The pulse provides the initial logical condition that determines whether the while-iterator subsystem is enabled in each time step. A Dashboard Scope block is connected to the Iteration Number signal to display the output of the while-iterator subsystem.

Simulate the model. You can use debugging utilities in the Simulink® Editor to analyze the algorithm implemented in the while-iterator subsystem and understand the signal displayed in the Dashboard Scope block.

Add Port Value Labels

To understand how signal values change as the simulation progresses, you can add port value labels to signals of interest throughout your model before and during simulation. The port value label is displayed in the model canvas, near the port that produces the signal.

To add a port value label on the Sine Wave signal:

  1. Select the Sine Wave signal.

  2. On the Debug tab, under Tools, in the Port Values button group, click Show port value label on selected signal .

You can also add port value labels to multiple signals at once. To add port value labels for the Pulse and Iteration Number signals:

  1. Select the Pulse signal.

  2. Press Shift and select the Iteration Number signal.

  3. On the Debug tab, in the Port Values button group, click Show port value label on selected signal .

New port value labels display no data yet until the next time the block that produces the signal executes.

Port value labels show "no data yet" for the Sine Wave, Pulse, and Iteration Number signals in the model IterateSum.

Set Breakpoint to Pause Within Time Step

By default, models are configured to pause within a time step as soon as the condition for a breakpoint is met. To check whether your model is configured to pause within a time step, open the Breakpoints List. In the Simulink® Toolstrip, on the Debug tab, click Breakpoints List. Check that Pause within time step is selected.

To pause execution within a time step so you can analyze the model by advancing the simulation one block at a time, set a breakpoint. The simulation pauses within the time step as soon as the condition for the breakpoint is met. For example, to pause just before the while-iterator subsystem gets enabled, set a breakpoint on the output of the Pulse block.

  1. Select the Pulse signal.

  2. On the Debug tab, under Breakpoints, click Add Breakpoint.

  3. In the Add Breakpoint dialog box, configure the signal breakpoint condition so the simulation pauses when the Pulse block output value becomes greater than zero. From the drop-down list, select > and then enter 0 in the box.

Because the while-iterator subsystem executes only when the Pulse signal value is not 0, this signal breakpoint causes the simulation to pause before each time the while-iterator subsystem executes.

The red circle on the signal line indicates the active signal breakpoint.

The model IterateSum has port value labels on all signals in the top model and an active breakpoint on the Pulse signal.

Step Through Block Execution

To start analyzing the model, run a simulation. In the Simulink Toolstrip, on the Debug tab, click Run.

When the simulation reaches a time of 0.5 seconds, the Pulse signal value becomes 1. The simulation pauses on the breakpoint just after the Pulse block executes and updates the output value. To indicate why and where the simulation paused, the breakpoint is annotated with a green arrow, and the Pulse block is highlighted green.

The model IterateSum paused on the Pulse signal breakpoint. The port value label for the Sine Wave signal shows a value of 86.6. The port value label for the Pulse signal shows 1. The port value label for the Iteration Number signal shows a value of 0.

To step the simulation execution to the next block, in the Debug tab, click Step Over. The green highlight moves to the while-iterator subsystem, and the green arrow on the breakpoint disappears.

The model IterateSum paused on the while-iterator subsystem. The port value labels show the same values for all three signals.

To see the number of iterations the while-iterator subsystem executes in this time step, click Step Over again. Because the while-iterator subsystem is nonvirtual, the Step Over action steps over the entire subsystem as a single unit. The port value label updates to show that the while-iterator subsystem executed the algorithm 13 times for an input value of 86.6.

The model IterateSum paused on the Outport block after stepping over the While Iterator Subsystem block. The port value label for the Iteration Number signal now displays the signal value as 13.

If you click Step Over one more time, the Outport block executes, and the Dashboard Scope block updates to show the new value for the Iteration Number signal.

If you continue clicking Step Over, you can step through the block-by-block execution in subsequent major time steps. The Pulse signal value stays 1 for the next several time steps.

Each time the simulation pauses on the Pulse block after you click Step Over, clicking Step Over again causes the simulation to pause on the breakpoint. The first time the simulation pauses on the Pulse block, the simulation pauses just before the Pulse block runs its output method. The second time the simulation pauses on the breakpoint is because the condition is met when the Pulse block runs its output method.

Step into While-Iterator Subsystem

To progress the simulation until the next time the while-iterator subsystem is enabled, in the Debug tab, click Continue. If you did not continue stepping block by block until the Pulse block output value changed to 0, continue clicking Continue until the simulation reaches a time of 1.5 seconds and pauses on the breakpoint.

To progress the simulation to the while-iterator subsystem, click Step Over. Then, to observe the algorithm, click Step In. The model canvas navigates inside the while-iterator subsystem. The simulation pauses on the Display block just before it executes to update the displayed value. The block displays 14 from the last time it executed.

The contents of the while-iterator subsystem. The Display block is highlighted green.

To see the signal values as you step through the algorithm implemented in the while-iterator subsystem, add port value labels.

  1. Select everything in the block diagram by clicking in the upper left of the canvas and holding while you drag the pointer to the lower right of the canvas or pressing Ctrl+A.

  2. In the Debug tab, under Tools, in the Port Values button group, click Show port value label on selected signal .

The port value label for the iteration number output from the While Iterator block shows inaccessible, so that signal value is displayed using the Display block. The other port value labels show no data yet.

The contents of the while-iterator subsystem. The Display block is highlighted green, and port value labels appear on every single line.

Click Step Over. The Display block executes and the displayed value updates to 1 to indicate that this is the first iteration. The simulation pauses on the Memory block, which is next in the execution order.

The contents of the while-iterator subsystem. The Memory block is highlighted green.

As you click Step Over two more times, the simulation pauses on the Sum block then the Relational Operator block. When you click Step Over again, the canvas updates to show the top level block diagram because the while-iterator subsystem executes only once in this time step. When you click Step Over once more, the Dashboard Scope block plots the new value for the Iteration Number signal.

Pause on Specific Iteration

When you want to debug or analyze the algorithm inside an iterator subsystem, you can use a breakpoint inside the while-iterator subsystem to pause simulation on a particular iteration. Setting a breakpoint on the iteration number output from the While Iterator block is not supported. Where you place the breakpoint and the condition for the breakpoint depends on how your algorithm uses the iteration number.

In the example model, the algorithm computes the cumulative sum of the iteration number. To break on a particular iteration, you can add a breakpoint to the output of the Sum block or to the output of the Memory block. For example, suppose you want to analyze the algorithm for a time step where the while-iterator subsystem algorithm executes more than once. In the first iteration, the output of the Sum block becomes 1. In the second iteration, the Memory block output becomes 1. Add a signal breakpoint to the output of the Memory block to pause simulation when the value is greater than 0.

  1. To navigate inside the while-iterator subsystem, double-click the block in the model.

  2. Right-click the output signal of the Memory block.

  3. From the context menu, select Add Breakpoint.

    By default, clicking a signal line during simulation toggles whether the signal has a port value label. If you click the signal line to add a breakpoint and the port value label disappears, click the signal again to add the port value label back. The port value label shows no data yet until the block that produces the signal executes again. The software does not retain data for port value labels when they are removed.

  4. In the Add Breakpoint dialog box, configure the signal breakpoint condition so the simulation pauses when the signal value becomes greater than 0. From the drop-down list, select > and then enter 0 in the box.

The contents of the while-iterator subsystem. Port value labels display the signal values from the previous time step. A red circle indicates the breakpoint on the output of the Memory block.

To progress simulation directly to the first time the while-iterator subsystem executes more than once, disable the breakpoint on the Pulse signal.

  1. In the Debug tab, click Breakpoints List.

  2. In the Breakpoints List, in the Enabled column, clear the check box for the row that corresponds to the breakpoint on the Pulse signal.

The Breakpoints List displays a table that contains information about the two breakpoints configured in the model. The breakpoint on the output of the Memory block is enabled. The breakpoint on the output of the Pulse block is disabled.

To progress the simulation until the next time step that the while-iterator subsystem executes more than once, in the Debug tab, click Continue. The simulation runs to a simulation time of 3.5 seconds and pauses on the breakpoint on the Memory block output signal. The port value label for the Memory block output shows a value of 1. The other port value labels display the value from the last time the while-iterator subsystem executed.

The contents of the while-iterator subsystem. The Memory block is highlighted green. A green arrow on the breakpoint indicates the simulation paused on the breakpoint.

Continue clicking Step Over to step through the algorithm one block at a time. The while-iterator subsystem continues to execute so long as the cumulative sum is less than the input value from the Sine Wave block.

Because the simulation pauses on the breakpoint in each iteration, you can use the Continue button to step through the simulation one iteration at a time.

On the 13th iteration, the cumulative sum becomes 91, which is greater than the input value of 86.6. The port value label for the output of the Relational Operator block shows a value of true because the block has not executed yet.

The simulation is paused on the Relational Operator block that determines whether the input value is greater than the cumulative sum value in the current iteration.

When you click Step Over once more, the Relational Operator block executes, and the simulation exits the while-iterator subsystem loop. The model canvas navigates back to the top-level view of the model. If you click Step Over once more, the Outport block executes, and the plot in the Dashboard Scope block updates to show the value from this time step.

The model IterateSum paused between time steps. The Dashboard Scope shows a plot of the Iteration Number signal values for the simulation up to this time.

View Execution Order

To understand how the software steps from one block to the next, you can view the execution order on the block diagram while a simulation is paused. The execution order indicates the order in which the software executes each block during each major time step. Viewing the execution order can help you understand the behavior of your model and the progression of the simulation as you step block by block.

To advance the simulation to the next time step where the while-iterator subsystem executes more than once, click Continue. The Simulink Editor navigates inside the while-iterator subsystem, and the simulation pauses on the Memory block.

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 selected task and their order of execution.

The Simulink Editor shows the contents of the while-iterator subsystem and the Execution Order viewer. The model is highlighted and annotated to indicate the execution order.

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 Sum block, and the green highlight around the Sum block overlays the highlighting from the Execution Order viewer. The Execution Order viewer also highlights the Sum block in the Execution Order Block List.

The Simulink Editor shows the contents of the while-iterator subsystem and the Execution Order viewer. The green highlight on the Sum block overlays the execution order highlighting in the block diagram.

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.

  1. To open the Breakpoints List, on the Debug tab, click Breakpoints List.

  2. 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.

  3. To resume the simulation, click Continue.

To continue the simulation from the current time point without retaining breakpoints, remove all breakpoints from the model.

  1. To clear all breakpoints in the model, on the Debug tab, click the Add Breakpoint button arrow and select Clear All Breakpoints.

  2. 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

Tools

Blocks

Related Topics