Accessing Block Data During Simulation

About Block Run-Time Objects

Simulink provides an application programming interface, called the block run-time interface, that enables programmatic access to block data, such as block inputs and outputs, parameters, states, and work vectors, while a simulation is running. You can use this interface to access block run-time data from the MATLAB command line, the Simulink Debugger, and from Level-2 M-file S-functions (see Writing S-Functions in M).

Note   You can use this interface even when the model is paused or is running or paused in the debugger.

The block run-time interface consists of a set of Simulink data object classes (see Working with Data Objects) whose instances provide data about the blocks in a running model. In particular, the interface associates an instance of Simulink.RunTimeBlock, called the block's run-time object, with each nonvirtual block in the running model. A run-time object's methods and properties provide access to run-time data about the block's I/O ports, parameters, sample times, and states.

Back to Top

Accessing a Run-Time Object

Every nonvirtual block in a running model has a RuntimeObject parameter whose value, while the simulation is running, is a handle for the blocks' run-time object. This allows you to use get_param to obtain a block's run-time object. For example, the following statement

rto = get_param(gcb,'RuntimeObject');

returns the run-time object of the currently selected block.

Note   Virtual blocks (see Virtual Blocks) do not have run-time objects. Blocks eliminated during model compilation as an optimization also do not have run-time objects (see Block reduction). A run-time object exists only while the model containing the block is running or paused. If the model is stopped, get_param returns an empty handle. When you stop or pause a model, all existing handles for run-time objects become empty.

Back to Top

Listening for Method Execution Events

One application for the block run-time API is to collect diagnostic data at key points during simulation, such as the value of block states before or after blocks compute their outputs or derivatives. The block run-time API provides an event-listener mechanism that facilitates such applications. For more information, see the Simulink Reference for the add_exec_event_listener command. For an example of using method execution events, enter

sldemo_msfcn_lms

at the MATLAB command line. This Simulink model contains the S-function adapt_lms.m, which performs a system identification to determine the coefficients of an FIR filter. The S-function's PostPropagationSetup method initializes the block run-time object's DWork vector such that the second vector stores the filter coefficients calculated at each time step.

In the Simulink model, double-clicking on the annotation below the S-function block executes its OpenFcn. This function first opens a figure for plotting the FIR filter coefficients. It then executes the function add_adapt_coef_plot.m to add a PostOutputs method execution event to the S-function's block run-time object using the following lines of code.

% Get the full path to the S-function block
blk = 'sldemo_msfcn_lms/LMS Adaptive';

% Attach the event-listener function to the S-function
h   = add_exec_event_listener(blk, ...
         'PostOutputs', @plot_adapt_coefs);

The function plot_adapt_coefs.m is registered as an event listener that is executed after every call to the S-function's Outputs method. The function accesses the block run-time object's DWork vector and plots the filter coefficients calculated in the Outputs method. The calling syntax used in plot_adapt_coefs.m follows the standard needed for any listener. The first input argument is the S-function's block run-time object, and the second argument is a structure of event data, as shown below.

function plot_adapt_coefs(block, eventData)

% The figure's handle is stored in the block's UserData
hFig  = get_param(block.BlockHandle,'UserData');
tAxis = findobj(hFig, 'Type','axes');

tAxis = tAxis(2);
tLines = findobj(tAxis, 'Type','Line');

% The filter coefficients are stored in the block run-time
%   object's second DWork vector.
est = block.Dwork(2).Data;

set(tLines(3),'YData',est);

Back to Top

Synchronizing Run-Time Objects and Simulink Execution

Run-time objects can be used at the MATLAB command line to obtain the value of a block's output by entering the following commands.

rto = get_param(gcb,'RuntimeObject')
rto.OutputPort(1).Data

However, the displayed data may not be the block's true output if the run-time object is not sychronized with the Simulink execution. Simulink only ensures the run-time object and Simulink execution are synchronized when the run-time object is used either within a Level-2 M-file S-function or in an event listener callback. When called at the MATLAB command line, the run-time object can return incorrect output data if other blocks in the model are allowed to share memory.

To ensure the Data field contains the correct block output, turn off the Signal storage reuse option (see Signal storage reuse) on the Optimization pane in the Configuration Parameters dialog box.

Back to Top

Controlling and Displaying the Sorted Order

Working with Block Libraries

Related Products & Applications

• Simulink
• Control Design
• Signal Processing & Communications
• Model-Based Design
• Physical Modeling
• Verification & Validation

Get Simulink trial software

Learn more about Simulink through this collection of videos, articles, technical literature and the Getting Started with Simulink Guide.

Get this Simulink Kit