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 |
bafter | Set breakpoint that pauses simulation after specified method To clear breakpoints set using the |
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
|
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.
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 |
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 |
