Simulink - Using Embedded MATLAB Blocks in Simulink

Using Embedded MATLAB Blocks

The Embedded MATLAB Function Block is an easy and convenient way to write MATLAB m-code that can be incorporated into a Simulink model. This tutorial discusses the core features of the Embedded MATLAB Function block and presents an example model that uses the block.

Note that in release R2011a several blocks where renamed (although their functionality did not change). The Embedded MATLAB Function block was one such block.

The following table shows the name changes,

Block Name Pre-R2011a		Block Name (Post-)R2011a
MATLAB Function Block	→	Interpreted MATLAB Block
Embedded MATLAB Function Block	→	MATLAB Function Block

Note that pre- and post-R2011a there ia a block called the MATLAB Function Block, but it behaves very differently depending on the version of MATLAB being used.

This tutorial will refer to the pre-R2011a name: Embedded MATLAB Function Block.

The tutorial is split into the following sections,

General Description of the Embedded MATLAB Function Block.
Example Model and M-Code.

For additional examples of using the Embedded MATLAB Function block see any of the Kalman Filter examples. Other tutorials discussing Simulink and its applications for model based design are available on the Software Tutorials page.

General Description of the Embedded MATLAB Function Block

The Embedded MATLAB Function block is obtained from the User Defined Functions Library and is inserted into a model in the same way as any other Simulink block. (See the Inserting Blocks section within the Model Building with Simulink tutorial.)

Once in a model the m-code that represents the block’s functionality is associated with the block by writing it in an editor. The editor is very similar to the standard MATLAB Editor and is viewed by double clicking on the block. An example of this is shown in Figure 1.

Opening an Embedded MATLAB Block.

Figure 1: Opening an Embedded MATLAB Block.

The functionality of an Embedded MATLAB Function block is defined in an m-code function. Although the general syntax of the function is identical to the syntax that is used in any other m-code function there are some special considerations.

The input and output arguments of an Embedded MATLAB Function are interpreted in a special way. The function’s number of input arguments automatically corresponds to the number of block input ports and the function’s number of output arguments automatically corresponds to the number of block output ports. Similarly the input arguments automatically take on the size and data-type of input signals, and the output signals automatically take on the size and data-type of the output variables created in the function. This imposes the restriction that the size and data-type of output variables typically needs to be defined at the start of the m-code and not changed during the simulation.

Debugging an Embedded MATLAB Function Block is performed in exactly the same way as the debugging of a standard MATLAB function. Break-points may be inserted at any line in the code (within the editor), and when the model is executed the simulation will stop each time any line with a breakpoint is encountered. All of the usual ability to step through the code and inspect and/or change variables is available.

The Embedded MATLAB Function block works by converting the written m-code into an S-Function. (For a discussion of S-Functions see the Writing Simulink S-Functions tutorials.) All parts of the code that use a certain subset of the MATLAB language - called the Embedded Subset - are converted to C and compiled. All other parts of the code (i.e. the parts that use MATLAB code that is not part of the Embedded Subset) are executed by calling MATLAB’s (interpretive) engine in the usual way.

To view the list of functions that are in the Embedded MATLAB Subset type the following at the MATLAB command line

>> docsearch('Embedded MATLAB Function Library Alphabetical List');

To assist the parser in splitting the code into the two types (Embedded Subset and not Embedded Subset), all MATLAB functions called from within the code that are not part of the Embedded Subset must be specified as such. This is achieved using the function eml.extrinsic near the top of the Embedded MATLAB function. An example of using eml.extrinsic is given in the Example Model and M-Code section below.

When a block contains only m-code from the Embedded Subset the block may be used with Simulink Coder (formerly Real-Time Workshop) to generate standalone and/or embeddable code.

Although very convenient to use, there is a drawback to the Embedded MATLAB Function Block. That is that it does not have any capability to segment the code into individual parts that perform just ininitialization, simulation, or termination. All the code gets executed at every simulation time step. When special initialization and/or termination code is required then an S-Function is recommended.

Example Model and M-Code

In this example an Embedded MATLAB Function is written that accepts as input a vector of numbers and sorts those numbers into descending order.

The model under consideration is shown in Figure 1, and contains only 3 blocks: a Uniform Random Number generator; an Embedded MATLAB Function block; and a Display block. The Uniform Random Number generator block has its Seed parameter set to transpose(randperm(10)). This ensures that 10 independent random samples are output by the block at each time step. And the Display block has been expanded to enable 10 numbers to be shown. (The example code will handle an arbitrary length vector -- 10 has been chosen for convenience, but any positive integer will suffice.)

Two different versions of code for the Embedded MATLAB Function are presented. The first version uses MATLAB’s sort function. Since sort is not part of MATLAB’s Embedded Subset it must be defined using the eml.extrinsic function, and the code cannot be used with Simulink Coder to generate stand-alone code from the model. The second version uses purely code from MATLAB’s Embedded Subset. This implies that it is compatible with Simulink Coder.

As of release R2008a the sort function within the Embedded MATLAB Subset fully supports fixed-point arithmetic. Hence the following example is somewhat obsolete in that the eml.extrinsic line is no longer required. However, the example is still indicative of how to call other general MATLAB functions from an Embedded MATLAB Function.

Using MATLAB’s sort Function

An example of m-code that implements the required sorting using the extrinsic function sort is given in Figure 2. Note the use of eml.extrinsic near the top of the code, which tells the parser that the sort function should call MATLAB’s interpreter every time the code is executed.

function [vOut,iOut] = sortVector(vIn)
%#eml
% Embedded MATLAB Function to sort a vector input into descending order.
% An index vector specifying how the sort was performed is also output.

% Author: Phil Goddard (phil@goddardconsulting)

% We're going to use the MATLAB function called sort to do the sorting.
% Since it isn't in the Embedded Subset of MATLAB it must be defined as
% being extrinsic
eml.extrinsic('sort');
% Ensure the outputs are the same size and data-type as the input
vOut = vIn;
iOut = vIn;
% Perform the sort operation
[vOut,iOut] = sort(vIn,'descend');

Figure 2: Version of Code Using an Extrinsic Function.

Using a Custom Sort Function

An example of m-code that implements the required sorting using functionality purely from MATLAB’s Embedded Subset is shown in Figure 3. This version of the code is compatible with Simulink Coder should it be used in a model from which stand-alone C code is to be generated.

function [vOut,iOut] = sortVector(vIn)
%#eml
% Function to implement a vector sort algorithm.
% Used to sort the input vector into descending order and output the
% sorted vector along with the indices showing how the sort was achieved.
%
% This is NOT a bubble sort algorithm.
% It is orders of magnitude father than bubble sorting for vectors
% with more than about 10 elements.

% Author: Phil Goddard (phil@goddardconsulting.ca)

% Define the output data
vOut = vIn; % Initialize the output vector
iOut = (1:length(vOut))'; % Initialize the output indices vector
% Define some temporary data needed for the sorting algorithm
maxIndex = 0;
vMax = 0;
iMax = 0;

% Loop over all the wheels
for idx = 1:(length(vOut)-1)
    % Store the data for the current index
    maxIndex = idx;
    vMax = vOut(idx);
    iMax = iOut(idx);
    % Loop over remaining elements to see if any are bigger
    for jdx = (idx+1):length(vOut)
        if vOut(jdx) > vMax
            maxIndex = jdx;
            vMax = vOut(jdx);
            iMax = iOut(jdx);
        end
    end
    % If any are bigger then do a swap
    if (maxIndex~=idx)
        vOut(maxIndex) = vOut(idx);
        iOut(maxIndex) = iOut(idx);
        vOut(idx) = vMax;
        iOut(idx) = iMax;
    end
end

Figure 3: Version of Code Compatible With Simulink Coder.

This tutorial has discussed topics related to using the Embedded MATLAB Function block. For additional examples of using the Embedded MATLAB Function block see any of the Kalman Filter examples. Other Simulink tutorials are available on the Software Tutorials page.