sltrace.Graph

Signal path traced using sltrace function

Since R2021b

Description

An sltrace.Graph object stores information about a signal path traced using the sltrace function. Use the signal tracing programmatic interface to programmatically analyze the structure of a model by tracing a signal to one or more source or destination blocks. You can also use the signal tracing programmatic interface to build your own custom tracing tool.

You can use an sltrace.Graph object to:

• Highlight the signal path in the model.

• Highlight any block in the model, including blocks that are not on the signal path.

• Create a directed graph plot of the signal path.

Creation

Create an sltrace.Graph object by tracing a signal path using the sltrace function.

Properties

SrcBlocks — Source blocks on tracing path

array of block handles | array of Simulink.BlockPath objects

Source blocks on tracing path, returned as an array of block handles or an array of Simulink.BlockPath objects.

• When you do not specify the BlockPath name-value argument for the sltrace function or when you specify the BlockPath argument as 'off', the blocks are represented as block handles.

• When you specify the BlockPath name-value argument for the sltrace function as 'on', the blocks are represented as Simulink.BlockPath objects.

The SrcBlocks property has a value only for paths that trace a signal to one or more source blocks. When the sltrace.Graph object represents a signal path to destination blocks, the SrcBlocks property is empty.

DstBlocks — Destination blocks on tracing path

array of block handles | array of Simulink.BlockPath objects

Destination blocks on tracing path, returned as an array of block handles or an array of Simulink.BlockPath objects.

• When you do not specify the BlockPath name-value argument for the sltrace function or when you specify the BlockPath argument as 'off', the blocks are represented as block handles.

• When you specify the BlockPath name-value argument for the sltrace function as 'on', the blocks are represented as Simulink.BlockPath objects.

The DstBlocks property has a value only for paths that trace a signal to one or more destination blocks. When the sltrace.Graph object represents a signal path to source blocks, the DstBlocks property is empty.

TraceGraph — Directed graph representation of signal path

digraph object

Directed graph representation of signal path, returned as a digraph object. The directed graph consists of nodes and edges. Each node in the graph represents a block port. Each edge in the graph represents a connection between two block ports, such as a signal line in the model.

The digraph object has the properties Nodes and Edges, which contain details about each edge and node in the graph as a table.

For each node, the table includes information about how the node relates to the block diagram, including:

• Whether the node represents an input port or output port for the block

• Block identification

  By default, the block identification is the numeric block handle. When you specify the BlockPath name-value argument for the sltrace function as on, the block identification is a Simulink.BlockPath object.

For each edge, the table includes information about the connection, including a Segments column that indicates the type of connection.

• Empty — The segment connects two different blocks.

• 'Internal' — The segment connects two ports on the same block.

• 'Hidden' — The segment connects two blocks but has no corresponding signal line in the model. For example, the connection between a From block and a Goto block has this value in the Segments column.

Object Functions

highlight	Highlight path to signal sources or destinations in model
removeHighlight	Remove highlighting for sltrace.Graph object from model

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)

Version History

Introduced in R2021b