Quantcast

Documentation Center

  • Trial Software
  • Product Updates

Simulink.Bus.createMATLABStruct

Create MATLAB structures with same hierarchy and attributes as bus signals

Syntax

  • structForBus = Simulink.Bus.createMATLABStruct(busSource) example
  • structForBus = Simulink.Bus.createMATLABStruct(busSource,partialValues) example
  • structForBus = Simulink.Bus.createMATLABStruct(busSource,partialValues,dims) example
  • cellStructsForBuses = Simulink.Bus.createMATLABStruct(arrayOfPortHandles) example
  • cellStructsForBuses = Simulink.Bus.createMATLABStruct(arrayOfPortHandles,cellOfPartialStructs)

Description

example

structForBus = Simulink.Bus.createMATLABStruct(busSource) creates a MATLAB® structure with the same hierarchy and attributes (such as type and dimension) as a bus signal busSource. Specify either the name of a bus object or the handle of a bus signal port. The resulting structure uses the ground values of the bus signal.

example

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

example

structForBus = Simulink.Bus.createMATLABStruct(busSource,partialValues,dims) creates a structure with the specified dimensions. For the busSource argument, use the name of a bus object. You can specify an empty matrix ([]) for partialValues.

example

cellStructsForBuses = Simulink.Bus.createMATLABStruct(arrayOfPortHandles) creates a cell array of structures for bus signal ports arrayOfPortHandles. 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.

cellStructsForBuses = Simulink.Bus.createMATLABStruct(arrayOfPortHandles,cellOfPartialStructs) creates a cell array of structures. The corresponding fields in the structures use the specified values cellOfPartialStructs instead of the ground values.

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')

The simulated busic_example model looks like this:

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.

Close the system.

close_system('busic_example')

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')

The simulated busic_example model looks like this:

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

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

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

The Outport handle is the handle that you need.

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.

mStruct = Simulink.Bus.createMATLABStruct(ph.Outport,PartialStructForK)
mStruct = 

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

Close the system.

close_system('busic_example')

MATLAB Structure with Specified Dimensions

Open a Simulink model and simulate it.

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

The simulated busic_example model looks like this:

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.

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

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')

The simulated ex_two_outports_create_struct model looks like this:

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 signalname of bus object | port handle

Source representing a bus signal for which to create a MATLAB structure, specified as the name of a bus object (a Simulink.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, then that bus object must be in the MATLAB base workspace. The data type for the bus object is a 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: structForBus = 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. To create a structure for an array of buses, use dims.

If you use dims, it must be the third argument.

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

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

Data Types: double

arrayOfPortHandles — Handles of bus signal portsarray

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

Data Types: double

cellOfPartialStructs — Handles of bus signal portscell array

Handles of bus signal ports, specified as a cell array.

Data Types: cell

Output Arguments

expand all

structForBus — Bus signal hierarchy and attributes, returned as a MATLAB structureMATLAB structure

Structure of data with same hierarchy and attributes as a bus signal that you specify with a either a bus object or port handle. The structure uses ground values of the bus signal. To override ground values for specific nodes, specify a partialValuespartial structure.

The dimensions of structForBus 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.

cellStructsForBuses — Structures with same hierarchy and attributes as bus signalscell array

Structures with same hierarchy and attributes as bus signals, specified 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. To override other values for specific nodes in the resulting structures specify a cellOfPartialStructs cell array of partial structures.

The dimensions of cellStructsForBuses depend on the input arguments:

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

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

Tips

  • 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 icon ( ).

    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.

See Also

| | | | | | | | | | |

Was this topic helpful?