Simulink.Bus.createMATLABStruct

Create MATLAB structures that use same hierarchy and attributes as buses

Syntax

S = Simulink.Bus.createMATLABStruct(busSource)

S = Simulink.Bus.createMATLABStruct(busSource,vals)

S = Simulink.Bus.createMATLABStruct(busSource,vals,sdims)

S = Simulink.Bus.createMATLABStruct(busSource,vals,sdims,scope)

Description

S = Simulink.Bus.createMATLABStruct(busSource) creates one or more MATLAB^® structures that have the same hierarchy and attributes as the buses specified by busSource. The resulting structures use the ground values of the buses. Use this syntax to create initialization structures for multiple bus ports.

S = Simulink.Bus.createMATLABStruct(busSource,vals) creates one or more structures that use the values specified by vals.

S = Simulink.Bus.createMATLABStruct(busSource,vals,sdims) creates one or more structures that have the dimensions specified by sdims. To create a structure for an array of buses, include the sdims argument.

S = Simulink.Bus.createMATLABStruct(busSource,vals,sdims,scope) creates one or more structures in the data dictionary specified by scope.

Examples

Create MATLAB Structure from Bus Object

Open and compile the example model named BusInitialization. Compiling the model updates the line styles, which you can use to visually identify buses.

mdl = "BusInitialization";
open_system(mdl)
set_param(mdl,SimulationCommand="Update")

A preload callback in the model loads Simulink.Bus objects such as TopBus. The bus that passes through the Unit Delay block uses this bus object.

Create a MATLAB structure that has the same hierarchy and attributes as TopBus. Name the structure mstruct.

mstruct = Simulink.Bus.createMATLABStruct("TopBus")

mstruct = struct with fields:
    A: [1x1 struct]
    B: 0
    C: [1x1 struct]

The function assigns a ground value of 0 to each field in the structure.

Specify a value of 3 for the field that corresponds with TopBus.A.A1.

mstruct.A.A1 = 3;

The other fields in the structure continue to specify a value of 0.

To specify mstruct as the initial condition structure for the Unit Delay block, set the Initial condition block parameter to mstruct.

Create Cell Array of MATLAB Structures

To create initialization structures for buses at multiple ports, use multiple port handles with the Simulink.Bus.createMATLABStruct function. The resulting cell array of structures uses ground values.

Open and compile the example model named BusInitializationTwoPorts.

mdl = "BusInitializationTwoPorts";
open_system(mdl)
set_param(mdl,SimulationCommand="Update")

Get the handle of the output port for each Bus Creator block.

bc1 = "BusInitializationTwoPorts/Bus Creator";
ph1 = get_param(bc1,"PortHandles");
out1 = ph1.Outport;

bc2 = "BusInitializationTwoPorts/Bus Creator1";
ph2 = get_param(bc2,"PortHandles");
out2 = ph2.Outport;

To create a cell array that contains a structure for each bus, provide an array of port handles to the Simulink.Bus.createMATLABStruct function.

structs = Simulink.Bus.createMATLABStruct([out1 out2])

structs=2×1 cell array
    {1x1 struct}
    {1x1 struct}

Create MATLAB Structure from Port and Partial Structure

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

Open and compile the example model named BusInitialization. Compiling the model updates the line styles, which you can use to visually identify buses.

mdl = "BusInitialization";
open_system(mdl)
set_param(mdl,SimulationCommand="Update")

Create a partial structure that specifies values for a subset of the elements in the bus hierarchy. In the partial structure, specify values for the Top.A.A1 and Top.B elements.

pstruct = struct("A",struct("A1",4),"B",3)

pstruct = struct with fields:
    A: [1x1 struct]
    B: 3

To create a full structure, use the Simulink.Bus.createMATLABStruct function.

For the first input argument, get the handle of the Bus Creator block output port that produces the top-level bus.

bctop = "BusInitialization/Bus Creator3";
ph = get_param(bctop,"PortHandles");
out = ph.Outport;

For the second input argument, specify the partial structure. The partial structure overrides the ground values for the Top.A.A1 and Top.B elements.

fstruct = Simulink.Bus.createMATLABStruct(out,pstruct)

fstruct = struct with fields:
    A: [1x1 struct]
    B: 3
    C: [1x1 struct]

Initialize Signal Elements that Use 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 compile the example model named BusInitialization. Compiling the model updates the line styles, which you can use to visually identify buses.

mdl = "BusInitialization";
open_system(mdl)
set_param(mdl,SimulationCommand="Update")

Create a partial structure that specifies values for a subset of the elements in the bus hierarchy. In the partial structure, specify values for the elements Top.B and Top.C.C1.

The signal element Top.C.C1 uses the data type int16. To set the value of the C.C1 field of the structure, use a typed expression. Match the data type in the expression with the data type of the signal in the model.

pstruct = struct("B",3,"C",struct("C1",int16(5)));

To create a full structure, use the Simulink.Bus.createMATLABStruct function.

For the first input argument, get the port handle for the Bus Creator block output port that produces the top-level bus.

bctop = "BusInitialization/Bus Creator3";
ph = get_param(bctop,"PortHandles");
out = ph.Outport;

For the second input argument, specify the partial structure. The partial structure overrides the ground values for the Top.C.C1 and Top.B elements.

fstruct = Simulink.Bus.createMATLABStruct(out,pstruct);

Check the value of fstruct.C.C1.

fstruct.C.C1

ans = int16

5

This field uses the data type int16.

Create MATLAB Structure with Specified Dimensions

Open and compile the example model named BusInitialization. Compiling the model updates the line styles, which you can use to visually identify buses.

mdl = "BusInitialization";
open_system(mdl)
set_param(mdl,SimulationCommand="Update")

A preload callback in the model loads Simulink.Bus objects such as TopBus. The bus that passes through the Unit Delay block uses this bus object.

Create a partial structure for a subset of the bus elements in the top-level bus.

pstruct = struct("A",struct("A1",4),"B",3)  

pstruct = struct with fields:
    A: [1x1 struct]
    B: 3

Create a full structure using the Simulink.Bus object named TopBus, the partial structure named pstruct, and the dimensions for the resulting structure.

fstruct = Simulink.Bus.createMATLABStruct("TopBus",...
    pstruct,[2 3])

fstruct=2×3 struct array with fields:
    A
    B
    C

Input Arguments

busSource — Source of bus information

Simulink.Bus object name in quotes | port handle | cell array of Simulink.Bus object names | array of port handles

Source of the bus information, specified as a Simulink.Bus object name in quotes, port handle, cell array of Simulink.Bus object names, or array of port handles.

• If you specify a Simulink.Bus object, the Simulink.Bus object must be in the MATLAB base workspace or the data dictionary used by the model.

• If you specify a port handle, the model must compile successfully.

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

• If you use the sdims argument, specify busSource as a Simulink.Bus object or cell array of Simulink.Bus objects.

Specifying a cell array of Simulink.Bus object names or an array of port handles creates multiple structures with one Simulink.Bus.createMATLABStruct call and provides better performance than using separate Simulink.Bus.createMATLABStruct calls to create the structures.

Example: S = Simulink.Bus.createMATLABStruct('BusObject') specifies one bus source via a Simulink.Bus object name.

Example: S = Simulink.Bus.createMATLABStruct({'BusObject','BusObject1'}) specifies multiple bus sources via a cell array of Simulink.Bus object names.

Example: S = Simulink.Bus.createMATLABStruct(ph) specifies one bus source via a port handle.

Example: S = Simulink.Bus.createMATLABStruct([ph,ph1]) specifies multiple bus sources via an array of port handles.

vals — Values for subset of elements in resulting structure

[] | partial structure | cell array

Values for a subset of elements in the resulting structure, specified as an empty matrix ([]), partial structure, or cell array. The cell array must contain a partial structure or empty matrix for each specified source of bus information.

For information on creating partial structures, see Specify Initial Conditions for Bus Elements.

To use ground values, use an empty matrix.

Example: S = Simulink.Bus.createMATLABStruct('BusObject',PartialStruct)

Data Types: struct | cell

sdims — Dimensions of resulting structure

scalar | vector | cell array

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 a partial structure for the vals argument, each dimension element must be greater than or equal to its corresponding dimension element in the partial structure.

Example: S = Simulink.Bus.createMATLABStruct('BusObject',PartialStruct,[2 3])

Example: S = Simulink.Bus.createMATLABStruct({'Bus','Bus1','Bus2'},{[],[],[]},{1,2,3})

Data Types: double | cell

scope — Data dictionary to contain MATLAB structure

Simulink.data.Dictionary object

Data dictionary to contain MATLAB structure, specified as a Simulink.data.Dictionary object. Before you use this argument, represent the dictionary with a Simulink.data.Dictionary object by using, for example, the Simulink.data.dictionary.create or Simulink.data.dictionary.open function.

If scope is empty, the function uses the MATLAB base workspace as the source of the Bus objects.

Example: S = Simulink.Bus.createMATLABStruct({'Bus','Bus1','Bus2'},{[],[],[]},{1,1,1},dataDictionaryObject)

Output Arguments

S — Structures with same signal hierarchy and attributes as buses

MATLAB structure | cell array of MATLAB structures

Structures with the same signal hierarchy and attributes as buses, returned as a MATLAB structure or a cell array of MATLAB structures.

The structure dimensions depend on the input arguments you specify:

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

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

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

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. To improve speed, put the model in compile before using the function multiple times. For example, to put a model named mymodel in compile, use this command.

  mymodel([],[],[],'compile')

  After you create the MATLAB structure, terminate the compile by using this command.

  mymodel([],[],[],'term')

• The Type Editor can invoke the Simulink.Bus.createMATLABStruct function. In the Type Editor, right-click a Simulink.Bus object for which you want to create a MATLAB structure. Then, click Create MATLAB Structure.

  You can edit the MATLAB structure in the MATLAB Editor. To create or update the values in this structure, evaluate the code.

• You can use the Simulink.Bus.createMATLABStruct function to specify the initial value of the output of a referenced model.

Version History

Introduced in R2010a