Simulink.Bus.createMATLABStruct

Create MATLAB structures using same hierarchy and attributes as bus signals

Syntax

  • structFromBus = Simulink.Bus.createMATLABStruct(busSource) example
  • structFromBus = Simulink.Bus.createMATLABStruct(busSource,partialValues) example
  • structFromBus = Simulink.Bus.createMATLABStruct(busSource,partialValues,dims) example
  • structsForBuses = Simulink.Bus.createMATLABStruct(portHandles) example
  • structsForBuses = Simulink.Bus.createMATLABStruct(portHandles,partialStructures)
  • structsForBuses = Simulink.Bus.createMATLABStruct(busObjectNames)

Description

example

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.

example

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.

example

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.

example

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

expand all

MATLAB Structure from Bus Object

Open a Simulink® model and simulate it.

run([docroot '/toolbox/simulink/ug/examples/signals/busic_example.mdl']);
sim('busic_example')

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

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

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

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 = 

    A1: 3
    A2: [5x1 int8]sim
('busic_example')

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.

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 bus elements of the bus signal that connects to the port.

Open a Simulink model.

run([docroot '/toolbox/simulink/ug/examples/signals/busic_example.mdl']);
sim('busic_example')

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('busic_example/TopBus','PortHandles')
ph = 

      Inport: [143.0013 144.0013 145.0013]
     Outport: 34.0013
      Enable: []
     Trigger: []
       State: []
       LConn: []
       RConn: []
    Ifaction: []

Create a partial structure, which is a MATLAB structure that specifies values for a subset of bus elements for the bus signal created by the TopBus block.

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

    A: [1x1 struct]
    B: 3

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

You can use a partial structure as an optional argument when creating a MATLAB structure from a bus object or from a bus port.

Create a MATLAB structure 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 = 

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

MATLAB Structure Having Specified Dimensions

Open a Simulink model and simulate it.

run([docroot '/toolbox/simulink/ug/examples/signals/busic_example.mdl']);
sim('busic_example')

Create a partial structure, which is a MATLAB structure that specifies values for a subset of bus elements for the bus signal created by the TopBus block.

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

    A: [1x1 struct]
    B: 3

Create a MATLAB structure using the bus object Top (which the busic_example model loads), 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

Close the system.

close_system('busic_example')

Cell Array of MATLAB Structures

Open a Simulink model and simulate it.

open_system(docpath(fullfile(docroot,'toolbox','simulink',...
'examples','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 = 

    [1x1 struct]
    [1x1 struct]

Close the system.

close_system('ex_two_outports_create_struct')

Input Arguments

expand all

busSource — Source representing a bus signala 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');
structForPortHandle = Simulink.Bus.createMATLABStruct(port_handle_1);

partialValues — Values for a subset of leaf nodes of the resulting structurepartial 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 Match IC Structure Values to Corresponding Bus Element Data Characteristics.

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 structurevector

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 portsarray

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 structurescell 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 namescell array

Bus object names, specified as a cell array.

Data Types: cell

Output Arguments

expand all

structFromBus — Bus signal hierarchy and attributesMATLAB 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 signalscell array

Structures having 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 ReferenceDetailed Workflow for Managing Data with Model Reference example.

Was this topic helpful?