Simulink.Bus.createMATLABStruct

Package: Simulink.Bus

Create MATLAB structures using same hierarchy and attributes as bus signals

Syntax

structFromBus = Simulink.Bus.createMATLABStruct(busSource)

structFromBus = Simulink.Bus.createMATLABStruct(busSource,partialValues)

structFromBus = Simulink.Bus.createMATLABStruct(busSource,partialValues,dims)

structsForBuses = Simulink.Bus.createMATLABStruct(portHandles)

structsForBuses = Simulink.Bus.createMATLABStruct(portHandles,partialStructures)

structsForBuses = Simulink.Bus.createMATLABStruct(busObjectNames)

Description

structFromBus = Simulink.Bus.createMATLABStruct(busSource) creates a MATLAB^® structure that has the same hierarchy and attributes (such as type and dimension) as the bus specified in busSource. The resulting structure uses the ground values of the bus signal.

structFromBus = Simulink.Bus.createMATLABStruct(busSource,partialValues) creates a structure that uses specified values of partialValues instead of the corresponding ground values of the bus signal.

structFromBus = Simulink.Bus.createMATLABStruct(busSource,partialValues,dims) creates a structure that has the specified dimensions. To create a structure for an array of buses, use dims.

structsForBuses = Simulink.Bus.createMATLABStruct(portHandles) creates a cell array of structures for bus signal ports, specified with port handles. The resulting cell array of structures uses ground values. Use this syntax to create initialization structures for multiple bus ports. This syntax improves performance compared to using separate Simulink.Bus.createMATLABStruct calls to create the structures.

structsForBuses = Simulink.Bus.createMATLABStruct(portHandles,partialStructures) creates a cell array of structures that uses the specified values of partialStructures instead of the ground values.

structsForBuses = Simulink.Bus.createMATLABStruct(busObjectNames) creates a cell array of structures based on the specified bus objects.

Examples

Create MATLAB Structure from Bus Object

Open and simulate model ex_bus_initial_conditions.

open_system('ex_bus_initial_conditions')
sim('ex_bus_initial_conditions');

Create a MATLAB structure using bus object Top, which model ex_bus_initial_conditions loads.

mStruct = Simulink.Bus.createMATLABStruct('Top');

Set a value for the field of the mStruct structure that corresponds to bus element A1 of bus A.

mStruct.A.A1 = 3;
mStruct.A

ans = 

  struct with fields:

    A1: 3
    A2: [5x1 int8]

Simulink sets the other fields in the structure to the ground values of the corresponding bus elements.

You can use mStruct as the initial condition structure for the Unit Delay block.

Initialize Signal Elements that Use a Data Type Other than Double

Create a MATLAB structure for a bus whose signal elements use a data type other than double. Use a partial structure to specify initialization values for a subset of the elements. When you create the partial structure, match the data types of the fields with the data types of the corresponding elements.

Open and simulate model ex_bus_initial_conditions.

open_system('ex_bus_initial_conditions')
sim('ex_bus_initial_conditions');

The C1 signal element that the block labeled Constant5 produces uses the data type int16.

Find the port handle for the Bus Creator block port that produces the Top bus signal.

ph = get_param('ex_bus_initial_conditions/TopBus','PortHandles');

Create a partial structure that specifies values for a subset of the elements in the bus signal created by the TopBus block. To set the value of the C.C1 field, use a typed expression. Match the data type in the expression with the data type of the signal element in the model (int16).

PartialstructForK = struct('B',3,'C',struct('C1',int16(5)));

Create a full structure by using the port handle (ph) for the TopBus block. Override the ground values for the C.C1 and B elements.

outPort = ph.Outport;
mStruct = Simulink.Bus.createMATLABStruct(outPort,PartialstructForK);

The field C.C1 in the output structure continues to use the data type int16.

Create MATLAB Structure with Specified Dimensions

Open and simulate model ex_bus_initial_conditions.

open_system('ex_bus_initial_conditions')
sim('ex_bus_initial_conditions');

Create a partial structure for a subset of bus elements in the bus created by the TopBus block.

PartialStructForK = struct('A',struct('A1',4),'B',3)

PartialStructForK = 

  struct with fields:

    A: [1x1 struct]
    B: 3

Create a MATLAB structure using bus object Top, a partial structure, and dimensions for the resulting structure.

structFromBus = Simulink.Bus.createMATLABStruct...
     ('Top',PartialStructForK,[2 3])

structFromBus = 

  2x3 struct array with fields:

    A
    B
    C

Create Cell Array of MATLAB Structures

To create initialization structures for multiple bus ports, specify port handles as arguments for Simulink.Bus.createMATLABStruct. The resulting cell array of structures uses ground values.

Open and simulate model ex_two_outports_create_struct.

open_system('ex_two_outports_create_struct')
sim('ex_two_outports_create_struct');

Find the port handles for the Bus Creator blocks Bus1 and Bus2.

ph_1 = get_param...
     ('ex_two_outports_create_struct/Bus Creator','PortHandles');
ph_2 = get_param...
     ('ex_two_outports_create_struct/Bus Creator1','PortHandles');

Create a MATLAB® structure using an array of port handles.

mStruct = Simulink.Bus.createMATLABStruct([ph_1.Outport ph_2.Outport])

mStruct =

  2x1 cell array

    {1x1 struct}
    {1x1 struct}

Create MATLAB Structure from Bus Port and Partial Structure

Create a MATLAB structure based on a port that connects to a bus signal. Use a partial structure to specify values for a subset of the bus elements in the bus that connects to the port.

Open and simulate model ex_bus_initial_conditions.

open_system('ex_bus_initial_conditions')
sim('ex_bus_initial_conditions');

Find the port handle for the Bus Creator block port that produces the Top bus signal. The Outport handle is the handle that you need.

ph = get_param('ex_bus_initial_conditions/TopBus','PortHandles')

ph = 

  struct with fields:

      Inport: [27.0023 31.0023 43.0023]
     Outport: 44.0023
      Enable: []
     Trigger: []
       State: []
       LConn: []
       RConn: []
    Ifaction: []
       Reset: []

Create a partial structure for the bus signal created by the TopBus block. You can use a partial structure to specify values for a subset of bus elements.

PartialstructForK = struct('A',struct('A1',4),'B',3)

PartialstructForK = 

  struct with fields:

    A: [1x1 struct]
    B: 3

Bus elements represented by structure fields Top.B and Top.A are at the same level in the bus hierarchy. You can use this partial structure to override the ground values for the B and A bus signal elements.

When you create a structure from a bus object or from a bus port, you can use a partial structure as an optional argument.

Create a MATLAB structure by using the port handle (ph) for the TopBus block. Override the ground values for the A.A1 and B bus elements.

outPort = ph.Outport;
mStruct = Simulink.Bus.createMATLABStruct(outPort,PartialstructForK)

mStruct = 

  struct with fields:

    A: [1x1 struct]
    B: 3
    C: [1x1 struct]

Input Arguments

busSource — Source representing a bus signal

a Simulink.Bus object | port handle

Source representing a bus signal to use for creating a MATLAB structure, specified as the name of a bus object or port handle.

• If you use the dims argument, then for busSource, use a bus object.

• For an array of buses signal, you cannot use a port handle.

• If you use a bus object name, then the bus object must be in the MATLAB base workspace. The data type for the bus object name is char.

• If you use a port handle, then the model must compile successfully before you use the createMATLABStruct method. The data type for the port handle is a double.

Example: structFromBus = Simulink.Bus.createMATLABStruct('myBusObject')

Example: structForPortHandle = Simulink.Bus.createMATLABStruct(port_handle_1)

partialValues — Values for a subset of leaf nodes of the resulting structure

partial structure | []

Values for a subset of leaf nodes of the resulting structure, specified as a partial structure or empty array. Each field that you specify in a partial structure must match the data attributes of the corresponding bus element exactly. For details, see Create Partial Structures for Initialization.

Use an empty matrix [] when you use the dims argument and want to use ground values for all of the nodes in the resulting structure.

Data Types: struct

dims — Dimensions of the resulting structure

vector

Dimensions of the resulting structure, specified as a vector.

Each dimension element must be an integer that is greater than or equal to 1. If you specify partialValues, then each dimension element in dims must be greater than or equal to its corresponding dimension element in the partial structure.

To use ground values, use an empty matrix ([]) for partialValues .

Data Types: double

portHandles — Handles of bus signal ports

array

Handles of bus signal ports, specified as an array. If you use the partialStructures argument, then the number of port handles that you specify in portHandles must be the same as the number of partial structures.

Data Types: double

partialStructures — Partial structures

cell array

Partial structures specified as a cell array. The number of port handles that you specify in portHandles must be the same as the number of partial structures.

Data Types: cell

busObjectNames — Bus object names

cell array

Bus object names, specified as a cell array.

Data Types: cell

Output Arguments

structFromBus — Bus signal hierarchy and attributes

MATLAB structure

Bus signal hierarchy and attributes, returned as a MATLAB structure.

The dimensions of structFromBus depend on the input arguments:

• If you specify only busSource, then the dimension is 1.

• If you also specify partialValues, then the dimensions match the dimensions of partialValues.

• If you specify the dims argument, then the dimensions match the dimensions of dims.

structsForBuses — Structures having the same hierarchy and attributes as bus signals

cell array

Structures with the same hierarchy and attributes as bus signals, returned as a cell array of structures of data with same hierarchy and attributes as a bus signals that you specify with an array of port handles. The cell array of structures uses ground values of the bus signals.

The dimensions of StructsForBuses depend on the input arguments:

• If you specify only portHandles, then the dimension is 1.

• If you also specify partialStructures, then the dimensions match the dimensions of partialStructures.

Tips

• If you use the Simulink.Bus.createMATLABStruct function repeatedly for the same model (for example, in a loop in a script), you can improve performance by avoiding multiple model compilations. For improved speed, put the model in compile before using the function multiple times. For example, to put the vdp model in compile, use this command:

  [sys,x0,str,ts] = vdp([],[],[],'compile')

  After you create the MATLAB structure, terminate the compile. For example:

  vdp([],[],[],'term')

• You can use the Bus Editor to invoke the Simulink.Bus.createMATLABStruct function. Use one of these approaches:

  • Select the File > Create a MATLAB structure menu item.

  • Select the bus object for which you want to create a full MATLAB structure. Then, in the toolbar, click the Create a MATLAB structure button ().

  You can then edit the MATLAB structure in the MATLAB Editor and evaluate the code to create or update the values in this structure.

• You can use the Simulink.Bus.createMATLABStruct function to specify the initial value of the output of a referenced model. For details, see the “Referenced Model: Setting Initial Value for Bus Output” section of the Detailed Workflow for Managing Data with Model Reference example.