Working with Structures and Bus Signals

About Structures in MATLAB Function Blocks

MATLAB Function blocks support MATLAB structures (see Structures in the MATLAB getting started guide). In MATLAB Function blocks, you can define structure data as inputs or outputs that interact with bus signals. MATLAB Function blocks also support arrays of buses (for more information, see Combining Buses into an Array of Buses). You can also define structures inside MATLAB functions that are not part of MATLAB Function blocks (see Code Generation for MATLAB Structuresin the Code Generation from MATLAB documentation).

The following table summarizes how to create different types of structures in MATLAB Function blocks:

Structures in MATLAB Function blocks can contain fields of any type and size, including muxed signals, buses and arrays of structures.

Back to Top

Example of Structures in a MATLAB Function Block

For an example of how to use structures in a MATLAB Function block, open the model emldemo_bus_struct.

In this model, a MATLAB Function block receives a bus signal using the structure inbus at input port 1 and outputs two bus signals from the structures outbus at output port 1 and outbus1 at output port 2. The input signal comes from the Bus Creator block MainBusCreator, which bundles signals ele1, ele2, and ele3. The signal ele3 is the output of another Bus Creator block SubBusCreator, which bundles the signals a1 and a2. The structure outbus connects to a Bus Selector block BusSelector1; the structure outbus1 connects to another Bus Selector block BusSelector3.

To explore the MATLAB function fcn, double-click the MATLAB Function block. Notice that the code implicitly defines a local structure variable mystruct using the struct function, and uses this local structure variable to initialize the value of the first output outbus. It initializes the second output outbus1 to the value of field ele3 of structure inbus.

Structure Definitions in Example

Here are the definitions of the structures in the MATLAB Function block in the example, as they appear in the Ports and Data Manager:

Bus Objects Define Structure Inputs and Outputs

Each structure input and output must be defined by a Simulink.Bus object in the base workspace (see Workflow for Creating Structures in MATLAB Function Blocks). This means that the structure shares the same properties as the bus object, including number, name, type, and sequence of fields. In this example, the following bus objects define the structure inputs and outputs:

The Simulink.Bus object MainBus defines structure input inbus and structure output outbus. The Simulink.Bus object SubBus defines structure output outbus1. Based on these definitions, inbus and outbus have the same properties as MainBus and, therefore, reference their fields by the same names as the fields in MainBus, using dot notation (see Indexing Substructures and Fields). Similarly, outbus1 references its fields by the same names as the fields in SubBus. Here are the field references for each structure in this example:

To learn how to define structures in MATLAB Function blocks, see Workflow for Creating Structures in MATLAB Function Blocks.

Back to Top

How Structure Inputs and Outputs Interface with Bus Signals

Buses in a Simulink model appear inside the MATLAB Function block as structures; structure outputs from the MATLAB Function block appear as buses in Simulink models. When you create structure inputs, the MATLAB Function block determines the type, size, and complexity of the structure from the input signal. When you create structure outputs, you must define their type, size, and complexity in the MATLAB function.

You connect structure inputs and outputs from MATLAB Function blocks to any bus signal, including:

• Blocks that output bus signals — such as Bus Creator blocks

• Blocks that accept bus signals as input — such as Bus Selector and Gain blocks

• S-Function blocks

• Other MATLAB Function blocks

Working with Virtual and Nonvirtual Buses

MATLAB Function blocks supports nonvirtual buses only (see Virtual and Nonvirtual Buses in the Simulink User's Guide). When models that contain MATLAB Function block inputs and outputs are built, hidden converter blocks are used to convert bus signals for code generation from MATLAB, as follows:

• Converts incoming virtual bus signals to nonvirtual buses for inputs to structures in MATLAB Function blocks

• Converts outgoing nonvirtual bus signals from MATLAB Function blocks to virtual bus signals

Back to Top

Rules for Defining Structures in MATLAB Function Blocks

Follow these rules when defining structures in MATLAB Function blocks:

• For each structure input or output in a MATLAB Function block, you must define a Simulink.Bus object in the base workspace to specify its type. For more information, see Simulink.Bus.

• MATLAB Function blocks support nonvirtual buses only (see Working with Virtual and Nonvirtual Buses).

Back to Top

Workflow for Creating Structures in MATLAB Function Blocks

Here is the workflow for creating a structure in a MATLAB Function block:

1. Decide on the type (or scope) of the structure (see About Structures in MATLAB Function Blocks).

2. Based on the scope, follow these guidelines for creating the structure:

   For Structure Scope:	Follow These Steps:
   Input	Create a Simulink.Bus object in the base workspace to define the structure input. Add data to the MATLAB Function block, as described in Adding Data to a MATLAB Function Block. The data should have the following properties Scope = Input Type = Bus: <object name> For <object name>, enter the name of the Simulink.Bus object that defines the structure input See Rules for Defining Structures in MATLAB Function Blocks.
   Output	Create a Simulink.Bus object in the base workspace to define the structure output. Add data to the MATLAB Function block with the following properties: Scope = Output Type = Bus: <object name> For <object name>, enter the name of the Simulink.Bus object that defines the structure output Define and initialize the output structure implicitly as a variable in the MATLAB function, as described in Code Generation for MATLAB Structures in the Code Generation from MATLAB documentation. Make sure the number, type, and size of fields in the output structure variable definition match the properties of the Simulink.Bus object.
   Local	Define the structure implicitly as a local variable in the MATLAB function, as described in Code Generation for MATLAB Structures in the Code Generation from MATLAB documentation. By default, local variables in MATLAB Function blocks are temporary.
   Persistent	Define the structure implicitly as a persistent variable in the MATLAB function, as described in Making Structures Persistent in the Code Generation from MATLAB documentation.
   Parameter	Create a structure variable in the base workspace. Add data to the MATLAB Function block with the following properties: Name = same name as the structure variable you created in step 1. Scope = Parameter See Working with Structure Parameters in MATLAB Function Blocks.

Back to Top

Indexing Substructures and Fields

As in MATLAB, you index substructures and fields structures in MATLAB Function blocks by using dot notation. However, for code generation from MATLAB, you must reference field values individually (see How Working with Structures Is Different for Code Generation in the Code Generation from MATLAB documentation).

For example, in the emldemo_bus_struct model described in Example of Structures in a MATLAB Function Block, the MATLAB function uses dot notation to index fields and substructures:

function [outbus, outbus1] = fcn(inbus)
%#codegen
substruct.a1 = inbus.ele3.a1;
substruct.a2 = int8([1 2;3 4]);

mystruct = struct('ele1',20.5,'ele2',single(100),
                  'ele3',substruct);

outbus = mystruct;
outbus.ele3.a2 = 2*(substruct.a2);

outbus1 = inbus.ele3;

The following table shows how the code generation software resolves symbols in dot notation for indexing elements of the structures in this example:

Back to Top

Assigning Values to Structures and Fields

You can assign values to any structure, substructure, or field in a MATLAB Function block. Here are the guidelines:

For example, the following table presents valid and invalid structure assignments based on the specifications for the model described in Example of Structures in a MATLAB Function Block:

Back to Top

Working with Structure Parameters in MATLAB Function Blocks

Defining Structure Parameters

To define structure parameters in MATLAB Function blocks, follow these steps:

1. Define and initialize a structure variable

   A common method is to create a structure in the base workspace. For other methods, see Working with Block Parameters.

2. In the Ports and Data Manager or Model Explorer, add data in the MATLAB Function block with the following properties:

   Property	What to Specify
   Name	Enter same name as the structure variable you defined in the base workspace
   Scope	Select Parameter
   Tunable	Leave checked if you want to change (tune) the value of the parameter during simulation; otherwise, clear to make the parameter non-tunable and preserve the initial value during simulation
   Type	Select Inherit: Same as Simulink

3. Click Apply.

FIMATH Properties of Non-Tunable Structure Parameters

FIMATH properties for non-tunable structure parameters containing fixed-point values are based on the initial values of the structure. They do not come from the FIMATH properties specified for fixed-point input signals to the parent MATLAB Function block. (These FIMATH properties appear in the properties dialog box for MATLAB Function blocks.)

Example: Using a Non-Tunable Structure Parameter to Initialize a Matrix

The following simple example uses a non-tunable structure parameter input to initialize a matrix output. The model looks like this:

This model defines a structure variable p in its pre-load callback function, as follows:

The structure p has two fields, rows and cols, which specify the dimensions of a matrix. The MATLAB Function block uses a constant input u to initialize the matrix output y. Here is the code:

function y = fcn(u, p)
y = zeros(p.rows,p.cols) + u;

Running the model initializes each element of the 2-by-3 matrix y to 99, the value of u:

Back to Top

Limitations of Structures and Buses in MATLAB Function Blocks

• Structures in MATLAB Function blocks support a subset of the operations available for MATLAB structures (see How Working with Structures Is Different for Code Generation in the Code Generation from MATLAB documentation).

• You cannot use variable-size data with arrays of buses (see Array of Buses Limitations).

Back to Top

Resolving Signal Objects for Output Data

Using Variable-Size 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