Access 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 MATLAB S-functions (see Write Level-2 MATLAB S-Functions).

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 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.

Access 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 run-time object of the block. 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. Run-time object data is read-only. You cannot use run-time objects to change a block’s parameters, input, output, and state data.

Note

Virtual blocks (see Nonvirtual and 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 a model, all existing handles for run-time objects become empty.

Listen 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 documentation 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.

% Add a callback for PostOutputs event
blk = 'sldemo_msfcn_lms/LMS Adaptive';

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, ei) %#ok<INUSD>
% 
% Callback function for plotting the current adaptive filtering
% coefficients.

stemPlot  = get_param(block.BlockHandle,'UserData');

est = block.Dwork(2).Data;
set(stemPlot(2),'YData',est);
drawnow('expose');

Synchronizing Run-Time Objects and Simulink Execution

You can use run-time objects to obtain the value of a block output and display in the MATLAB Command Window by entering the following commands.

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

However, the displayed data may not be the true block output if the run-time object is not synchronized 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 MATLAB S-function or in an event listener callback. When called from the MATLAB Command Window, 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, open the Configuration Parameters dialog box, and then clear the Signal storage reuse check box (see Signal storage reuse (Simulink Coder)).

Documentation