sltrace

Analyze structure of model by tracing signal sources and destinations

Since R2021b

Syntax

g = sltrace(p)

g = sltrace(blk,d)

g = sltrace(___,Name=Value)

Description

g = sltrace(p) traces the signal that connects to the port p and returns the traced signal path information as the sltrace.Graph object g.

• When the specified port is a block input port, the function traces the signal to the first nonvirtual source block.

• When the specified port is a block output port, the function traces the signal to the first nonvirtual destination block.

g = sltrace(blk,d) traces signals connected to the input or output ports of the block blk to the first nonvirtual source or destination block according to the specified direction d.

g = sltrace(___,Name=Value) traces the sources or destinations for a signal according to options specified using one or more name-value arguments. For example, when you specify the TraceAll argument as on, the function traces a signal to all source or destination blocks.

Examples

Trace All Sources for Signal

The model for this example implements the second-order differential Van der Pol (vdp) equation.

$\frac{{\mathit{d}}^2\mathit{x}}{\mathit{d}{\mathit{t}}^2}-\mu \left(1-{\mathit{x}}^2\right)\frac{\mathit{dx}}{\mathit{dt}}+\mathit{x}=0$,

where $\mu$ represents damping in the system.

Open the model vdp. In the model, the signal x1 represents the first derivative of $\mathit{x}$. The signal x2 represents the second derivative of $\mathit{x}$.

mdl = "vdp";
open_system(mdl)

Use the sltrace function to trace all source blocks for the signal x2, which is the input signal for the Integrator block named x1.

x2Sources = sltrace((mdl + "/x1"),"Source",Port=1,TraceAll="on");

When you trace all sources for a signal, the sltrace.Graph object that the sltrace function returns contains information about more than just the blocks that produce the input signals for the specified block. The sltrace.Graph object contains information for all blocks that produce output values that affect the value of the signal you trace.

length(x2Sources.SrcBlocks)

ans = 
10

To see the signal path in the block diagram, use the highlight function to highlight all the source blocks in the sltrace.Graph object x2Sources. The source blocks in the sltrace.Graph object and the signals that connect them are highlighted yellow in the block diagram. Highlighting the blocks also shades the canvas a darker gray to make the highlighting more visible.

highlight(x2Sources)

The sltrace.Graph object includes a digraph object you can use to analyze the connections among the source blocks. Each node in the graph represents a block port, and each edge, or line, represents a signal line.

plot(x2Sources.TraceGraph)

Once you have an sltrace.Graph object, you can use the highlight function to highlight any block or signal line in the model, including blocks and signal lines that are not part of the signal trace information in the sltrace.Graph object. For example, highlight the Scope block and the signal lines connected to the input ports on the Scope block.

Use the get_param function to get the block handle for the Scope block.

scopePath = mdl + "/Scope";
scopeHandle = get_param(scopePath,"Handle");

Use the get_param function to get the port handles for the Scope block.

scopePorts = get_param(scopePath,"PortHandles");

Use the get_param function to get the line handle for the signal line connected to each input port of the Scope block.

scopeIn1 = scopePorts.Inport(1);
scopeIn1 = get_param(scopeIn1,"Line");
scopeIn2 = scopePorts.Inport(2);
scopeIn2 = get_param(scopeIn2,"Line");

Use the highlight function to highlight the elements in the block diagram. The Scope block and the input signals for the Scope block are highlighted red in the block diagram, which still shows the yellow highlighting on the sources for the signal x2.

highlight(x2Sources,[scopeHandle scopeIn1 scopeIn2])

To remove the highlighting, use the removeHighlight function. The function removes all highlighting in the block diagram associated with the sltrace.Graph object. When the block diagram contains no highlighting, the shading in the canvas is also removed.

removeHighlight(x2Sources)

Input Arguments

p — Port from which to trace

port handle

Port from which to trace, specified as a port handle.

• When the specified port is a block input port, the function traces the signal to the first nonvirtual source block.

• When the specified port is a block output port, the function traces the signal to the first nonvirtual destination block.

blk — Block from which to trace

block handle | Simulink.BlockPath object | string | character vector

Block from which to trace, specified as a block handle, a Simulink.BlockPath object, or a string or a character vector that defines the path to a block.

d — Tracing direction

'Source' | 'Destination'

Tracing direction, specified as 'Source' or 'Destination'.

• 'Source' — Trace signals on block input ports to sources.

• 'Destination' — Trace signals on block output ports to destinations.

When you want to trace the sources or destinations for only one input or output port, use the Port name-value argument to specify the signal to trace.

When you want to trace the sources or destinations for a specific element within a bus, use the Element name-value argument to specify the element to trace.

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: sltrace(prt,TraceAll="on",BlockPath="on")

TraceAll — Option to trace signal to all sources or destinations

'off' (default) | 'on'

Option to trace to all sources or destinations, specified as 'off' or 'on'.

• 'off' — Trace the signal to the first nonvirtual source or destination block.

• 'on' — Trace the signal to all source or destination blocks.

Example: sltrace(blk,"Source",TraceAll="on") traces all sources for input signals of the block blk.

Data Types: char | string

Stop — Endpoint for tracing

block handle | Simulink.BlockPath object | string | character vector

Endpoint for tracing, specified as a block handle, a Simulink.BlockPath object, or a string or character vector that defines the path to a block.

If the specified block is not on the tracing path for the signal, the function traces the signal to all source or destination blocks.

Example: sltrace(blk,"Destination",Stop="mdl/blk") traces the output signals of block blk to all destination blocks up to the block blk in the model mdl.

Port — Index of port from which to trace signal

real positive scalar

Index of port from which to trace, specified as a real positive scalar number.

Use this argument when you specify the signal path to trace as a block and direction and the block has multiple input or output ports.

• When you trace signal sources, specify the index of the input port to which the signal you want to trace connects.

• When you trace signal destinations, specify the index of the output port that produces the signal you want to trace.

When you do not specify this name-value argument, the function traces the signals on all input or output ports.

Example: sltrace("mdl/blk","Source",Port="2") traces all sources for the signal on output port 2 of the block blk in the model mdl.

Data Types: double | single

Element — Bus element from which to trace

string | character vector

Bus element from which to trace, specified as a string or a character vector that defines the name of the bus element.

Use this argument when you specify the signal path to trace as a block and direction and the block receives or produces a bus. When you do not specify this name-value argument, the function traces all bus elements.

Example: sltrace("mdl/blk","Destination",Element="b") traces the element b of the bus produced by the block blk in model mdl to the first nonvirtual destination block.

Data Types: char | string

BlockPath — Option to capture block information using Simulink.BlockPath objects

'off' (default) | 'on'

Option to capture block information using Simulink.BlockPath objects, specified as 'off' or 'on'. The sltrace.Graph object includes information about the source or destination blocks in the specified tracing path. This argument specifies how the block information is provided in the sltrace.Graph object.

• 'off' — The sltrace.Graph object contains the block handle for each source or destination block.

• 'on' — The sltrace.Graph object contains a Simulink.BlockPath object for each source or destination block.

Specify this name-value argument as 'on' when the model contains multiple instances of a referenced model.

Example: sltrace("mdl/blk","Source",BlockPath="on") traces all sources for input signals of the block blk in the model mdl and captures the block information using Simulink.BlockPath objects.

Output Arguments

g — Signal sources or destinations

sltrace.Graph object

Signal sources or destinations, returned as an sltrace.Graph object. The object includes information about blocks in the tracing path and a digraph object you can use to plot a directed graph of the path. You can use the highlight function to highlight the tracing path in the block diagram.

Version History

Introduced in R2021b

R2024b: sltrace function no longer opens model

To better support scripting workflows, the sltrace function now loads models instead of opening them. The highlight and removeHighlight functions still open the model to show the highlighted signal trace in the model.