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.

Function	Breakpoint 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 Name	Description
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 Name	Description
atrace	Display information each time algebraic loop is solved in simulation debugging session
states	Display current values for system states
strace	Display 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 Name	Description
slist	Display sorted list for model. The sorted list information includes the block ID for each block in the model.
ashow	Highlight algebraic loop in model during simulation debugging session.
bshow	Highlight in block diagram the block that corresponds to the specified block ID.
systems	Display list of nonvirtual subsystems in model or model hierarchy.
zclist	Display list of blocks that detect zero crossings.
status	Display 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.

Category	Function Name	Description
Display information about model	probe	Display 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
	states	Display 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