Using Variable-Size Data in MATLAB Function Blocks

What Is Variable-Size Data?

Variable-size data is data whose size may change at run time. By contrast, fixed-size data is data whose size is known and locked at compile time, and therefore cannot change at run time.

Back to Top

How MATLAB Function Blocks Implement Variable-Size Data

You can define variable-size arrays and matrices as inputs, outputs, and local data in MATLAB Function blocks. However, the block must be able to determine the upper bounds of variable-size data at compile time.

For more information about working with variable-size data, see How Working with Variable-Size Data Is Different for Code Generation in the Code Generation from MATLAB documentation. For more information about using variable-size data in Simulink, see Working with Variable-Size Signals in the Simulink documentation.

Back to Top

Enabling Support for Variable-Size Data

Support for variable-size data is enabled by default for MATLAB Function blocks. To modify this property for individual blocks:

1. In the MATLAB Function Block Editor, select Tools > Edit Data/Ports

   The Ports and Data Manager dialog box opens.

2. Select or clear the check box Support variable-size arrays.

Back to Top

Declaring Variable-Size Inputs and Outputs

1. In the MATLAB Function Block Editor, select Tools > Edit Data/Ports

   The Ports and Data Manager dialog box opens.

2. Select Add > Data

3. Select the Variable size check box.

4. Set Scope as either Input or Output.

5. Enter size:

   For:	What to Specify
   Input	Enter -1 to inherit size from Simulink or specify the explicit size and upper bound. For example, enter [2 4] to specify a 2-D matrix where the upper bounds are 2 for the first dimension and 4 for the second.
   Output	Specify the explicit size and upper bound.

Back to Top

Declaring Variable-Size Data Locally

Use the function coder.varsize to declare variable-size data locally, as described in Defining Variable-Size Data for Code Generation in the Code Generation from MATLAB documentation.

Back to Top

Simple Example: Defining and Using Variable-Size Data in MATLAB Function Blocks

• About the Example

• Simulink Model

• Source Signal

• MATLAB Function Block: uniquify

• MATLAB Function Block: avg

• Variable-Size Results

About the Example

The following example appears throughout this section to illustrate how MATLAB Function blocks exchange variable-size data with other Simulink blocks. The model uses a variable-size vector to store the values of a white noise signal. The size of the vector may vary at run time as the signal values get pruned by functions that:

• Filter out signal values that are not unique within a specified tolerance of each other

• Average every two signal values and output only the resulting means

Simulink Model

Open the example model by typing emldemo_process_signal at the MATLAB command prompt. The model contains the following blocks:

Source Signal

The band-limited white noise signal has these properties:

The size of the noise power value defines the size of the matrix that holds the signal values — in this case, a 1-by-9 vector of double values.

MATLAB Function Block: uniquify

This block filters out signal values that are not within a tolerance of 0.2 of each other. Here is the code:

function y = uniquify(u) %#codegen
y = uniquetol(u,0.2);

The uniquify function calls an external MATLAB function uniquetol to filter the signal values. uniquify passes the 1-by-9 vector of white noise signal values as the first argument and the tolerance value as the second argument. Here is the code for uniquetol:

function B = uniquetol(A,tol) %#codegen

A = sort(A);
coder.varsize('B',[1 100]);
B = A(1);
k = 1;
for i = 2:length(A)
    if abs(A(k) - A(i)) > tol
        B = [B A(i)];
        k = i;
    end
end

uniquetol returns the filtered values of A in an output vector B so that abs(B(i) - B(j)) > tol for all i and j. Every time Simulink samples the Band-Limited White Noise block, it generates a different set of random values for A. As a result, uniquetol may produce a different number of output signals in B each time it is called. To allow B to accommodate a variable number of elements, uniquetol declares it as variable-size data with an explicit upper bound:

coder.varsize('B',[1 100]);

In this statement, coder.varsize declares B as a vector whose first dimension is fixed at 1 and whose second dimension can grow to a maximum size of 100. Accordingly, output y of the uniquify block must also be variable sized so it can pass the values returned from uniquetol to the Unique values scope. Here are the properties of y:

For variable-size outputs, you must specify an explicit size and upper bound, shown here as [1 9].

MATLAB Function Block: avg

This block averages signal values filtered by the uniquify block as follows:

The avg function outputs the results to the Average values scope. Here is the code:

function y = avg(u) %#codegen

if numel(u) == 1
    y = u;
else
    k = numel(u)/2;
    if k ~= floor(k)
        u = u(2:numel(u));
    end
    y = nway(u,2);
end

Both input u and output y of avg are declared as variable-size vectors because the number of elements varies depending on how the uniquify function block filters the signal values. Input u inherits its size from the output of uniquify:

The avg function calls an external MATLAB function nway to calculate the average of every two consecutive signal values. Here is the code for nway:

function B = nway(A,n) %#codegen

assert(n>=1 && n<=numel(A));

B = zeros(1,numel(A)/n);
k = 1;
for i = 1 : numel(A)/n
     B(i) = mean(A(k + (0:n-1)));
     k = k + n;
end

Variable-Size Results

Simulating the model produces the following results:

• The uniquify block outputs a variable number of signal values each time it executes:

  

• The avg block outputs a variable number of signal values each time it executes — approximately half the number of the unique values:

  

Back to Top

Working with Structures and Bus Signals

Using Enumerated Data in MATLAB Function Blocks

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