Main Content

Simulink Debugging Programmatic Interface

You can use the Simulink® debugging programmatic interface to run a simulation of a model one method at a time. Blocks in Simulink are implemented as a set of methods that are called by the solver at specific times during each time step. Using breakpoints, you can control when the simulation pauses and examine the execution results to trace behavior in your model to specific blocks, parameters, or connections. You can set breakpoints for specific conditions throughout the model, such as zero crossings, or on block methods and signals.

Note

To debug a simulation using the Simulink debugging programmatic interface, you must start the simulation using the sldebug function or using the sim function with the debug name-value argument.

The Simulink Editor offers many of the same capabilities in the programmatic interface.

Use Simulink Debugging Functions

When you programmatically debug a simulation, you start the simulation using the sldebug function. After you call the sldebug function, the MATLAB® command prompt becomes the sldebug command prompt. Instead of >>, you see (sldebug @0): >>. To control the debugging session, enter debugging commands in the MATLAB Command Window, at the sldebug command prompt.

For ease of use, the Simulink debugging programmatic interface accepts abbreviations for the debugging functions. For example, to call the step function, instead of entering the command step, you can enter the command s.

Use MATLAB Functions

You can enter any MATLAB expression at the sldebug command prompt. For example, suppose you are paused on a breakpoint and the simulation logs the time and output of your model as tout and yout. You can enter this command at the sldebug command prompt to create a plot.

plot(tout,yout)

Some MATLAB functions have the same name as or a similar name to a function in the Simulink debugging programmatic interface. To view the contents of a variable or to call a function with a name that partially or entirely matches the name of one of the Simulink debugging functions, use the eval function. For example, suppose the workspace contains the variable s. To display the contents of the variable instead of calling the step function, use this command.

eval('s')

Understand Block and Method IDs

Some of the debugging functions and messages use a numeric block ID or method ID to refer to a specific block or method in the model. Block IDs and method IDs are numeric values that the software assigns to each block and method in the simulation during run time.

The software assigns block IDs while generating the sorted order and execution list for the model during the compilation phase of the simulation. A block ID has the form (t)s:b, where t is an integer that identifies the task in which the block executes, s is an integer that identifies the system that contains the block, and b is an integer that indicates the position of the block in the execution list for that system. For example, the block ID (0)0:1 refers to the first block in the root system of a model. You can use the slist function to see the block ID for each nonvirtual block in the model.

Set and Manage Breakpoints

In a simulation debugging session, you can set breakpoints, or points of interest where you want to pause the simulation to analyze the system. Using the continue function, you can run a simulation from one breakpoint hit to the next.

Breakpoints are useful when you know that a problem or behavior you want to investigate occurs at a certain point in your model or when a certain condition occurs. By defining an appropriate breakpoint and running the simulation using the continue function, you can run the simulation without interruption up to the point in the simulation you want to investigate.

Note

When the simulation pauses on a breakpoint of a MATLAB S-function, to close MATLAB, you must first end the simulation debugging session.

The table summarizes functions available for setting breakpoints programmatically.

FunctionBreakpoint Behavior
break

Set breakpoint that pauses simulation on specified method

To clear breakpoints set using the break function, use the clear function.

bafter

Set breakpoint that pauses simulation after specified method

To clear breakpoints set using the bafter function, use the clear function.

tbreak [t]

Set or clear breakpoint that pauses simulation at specified simulation time step

ebreak

Set or clear breakpoint that pauses simulation when recoverable solver error occurs

nanbreak

Set or clear breakpoint that pauses simulation when NaN or infinite (Inf) value occurs

xbreak

Set or clear breakpoint that pauses simulation when the solver limits the step size for a variable-step simulation

zcbreak

Set or clear breakpoint that pauses simulation when a nonsampled zero-crossing event occurs

Display Information About the Simulation

You can use several functions to display run-time information about the simulation during a simulation debugging session.

The table summarizes options available to display information about blocks in the model during simulation, including the block input and output values. The level of information displayed when you call each of these functions depends on the software configuration. To specify the level of information to display, use the probe function.

Function NameDescription
probe

Displays data for specified block when you issue command

disp

Displays data for specified block when the simulation pauses

trace

Displays data for specified block each time the block executes

The table summarizes other options available for displaying run-time information about the model in simulation.

Function NameDescription
atraceDisplay information each time algebraic loop is solved in simulation debugging session
statesDisplay current values for system states
straceDisplay solver information in simulation debugging session

Display Information About the Model

The table summarizes functions you can use to display information about the model.

Function NameDescription
slist

Display sorted list for model.

The sorted list information includes the block ID for each block in the model.

ashowHighlight algebraic loop in model during simulation debugging session.
bshowHighlight in block diagram the block that corresponds to the specified block ID.
systemsDisplay list of nonvirtual subsystems in model or model hierarchy.
zclistDisplay list of blocks that detect zero crossings.
statusDisplay list of debugging options in effect for current simulation debugging session.

Use Simulation Debugging Commands While Debugging from Simulink Editor

When you start a simulation debugging session using the Simulink Editor, you can issue some of the simulation debugging commands, such as disp and probe, when the simulation is paused within a time step. To start a simulation debugging session from the Simulink Editor, add one or more breakpoints to your model. Then, in the Breakpoints List, check that Pause within time step is selected.

When a debug simulation started from the Simulink Editor pauses within a time step, the sldebug prompt replaces the MATLAB command prompt (>>) in the MATLAB Command Window. (since R2024a)

The table describes the programmatic simulation debugging commands that you can use while paused within a time step in a simulation debugging sessions started from the Simulink Editor.

CategoryFunction NameDescription

Display information about model

probeDisplay input, output, and state data for specified block
elist

Display execution order

slist

Display sorted list of blocks in model

stimes

Display information about sample times in model

systems

List nonvirtual subsystems in model or model hierarchy

statesDisplay state values
zclist

List blocks that detect zero crossings

Highlight blocks or algebraic loops in block diagram

bshow

Highlight specified block in model

ashow

Identify and highlight algebraic loops

Add or remove model-level breakpoints

nanbreak

Set or clear breakpoint to pause when Inf or NaN value occurs

zcbreak

Set or clear breakpoint to pause when nonsampled zero-crossing events occur

Add and remove trace points

trace

Display information about specified block each time block executes

atrace

Display information each time algebraic loop is solved

etrace

Display information when entering and exiting methods

strace

Display solver information

untrace

Remove trace point

Get information about simulation debugging session, access help, or end simulation debugging session

status

Display options used in current simulation debugging session

where

Display current location within simulation loop

help

Display help for Simulink debugging programmatic interface

stop

Stop simulation debugging session

See Also