Main Content

Simulink.Bus.createObject

Create Simulink.Bus objects from blocks or MATLAB structures

Description

example

busInfo = Simulink.Bus.createObject(model,blocks) creates Simulink.Bus objects for the specified blocks and returns information about the created Bus objects.

If you specify a block that corresponds to a bus hierarchy, this function creates Bus objects for each bus in the hierarchy.

If the model uses a data dictionary, the Bus objects are created in the data dictionary. Otherwise, they are created in the base workspace.

example

busInfo = Simulink.Bus.createObject(struct) creates Bus objects from a structure that can contain MATLAB® timeseries, MATLAB timetable, and matlab.io.datastore.SimulationDatastore objects or a numeric structure.

If you specify a structure with hierarchy, this function creates Bus objects for each structure in the hierarchy.

The Bus objects are created in the base workspace.

example

busInfo = Simulink.Bus.createObject(___,file) saves Bus objects in a function that defines object properties in a cell array of cell arrays, then creates the Bus objects by calling Simulink.Bus.cellToObject.

Specify any of the input argument combinations in the previous syntaxes followed by the file argument.

example

busInfo = Simulink.Bus.createObject(___,file,format) saves Bus objects in a function with the specified format. The function can define object properties using cell arrays or arrays.

busInfo = Simulink.Bus.createObject(struct,file,format,scope) creates the Bus objects in the data dictionary specified by scope.

Examples

collapse all

Open the example model.

open_system('BusObjectCreationModel')

Create a Bus object that corresponds with the bus created by the Bus Creator block.

busInfo = Simulink.Bus.createObject('BusObjectCreationModel',...
    'BusObjectCreationModel/Bus Creator');

Create Bus objects from two Bus Creator blocks and save the Bus object definition in a function.

Open the example model.

open_system('BusObjectCreationModel');

Assign the block handle for the Bus Creator block to a variable with the getSimulinkBlockHandle function.

bc = getSimulinkBlockHandle('BusObjectCreationModel/Bus Creator');

Alternatively, you can select a Bus Creator block in the model then use the gcbh function to get its block handle.

Assign the block handle for the Bus Creator1 block to a variable.

bc1 = getSimulinkBlockHandle('BusObjectCreationModel/Bus Creator1');

To create a Bus object, specify the block handle variables in a vector. To save the Bus object definition, also specify a file name.

busInfo = Simulink.Bus.createObject('BusObjectCreationModel',...
    [bc bc1], 'BusObjectFunction');

Since these Bus Creator blocks create a bus hierarchy, specifying only the Bus Creator1 block creates both Bus objects in the Workspace and in the function.

Compare the BusObjectFunction against the function created by this command.

topBusInfo = Simulink.Bus.createObject('BusObjectCreationModel',...
    bc1, 'BusObjectFunctionFromHierarchy');

For a function that is formatted to be easier to read, specify the function format as object.

topBusInfo1 = Simulink.Bus.createObject('BusObjectCreationModel',...
    bc1, 'BusObjectFunctionFormatted','object');

When you create a nonvirtual bus with a Constant block, you must specify a MATLAB structure for Constant value and a Simulink.Bus object as the Output data type.

For this example, create a structure that contains other structures.

bus_struct.A.A1 = 0;
bus_struct.A.A2 = [0 + 0i;0 + 0i;0 + 0i;0 + 0i;0 + 0i];
bus_struct.B = 5;
bus_struct.C.C1 = 0;
bus_struct.C.C2.A1 = 0;
bus_struct.C.C2.A2 = [0 + 0i;0 + 0i;0 + 0i;0 + 0i;0 + 0i];

Create the Bus objects that correspond with the structure.

busInfo = Simulink.Bus.createObject(bus_struct);

The function creates four Bus objects. The Bus object named slBus1 corresponds to the top-level structure and uses a default Bus object name. The Bus objects named A, C, and C2 correspond to the nested structures.

To view the Bus objects, open the Bus Editor.

buseditor

Input Arguments

collapse all

Model name or handle, specified as a character vector.

The model you specify must compile successfully.

Blocks associated with buses, specified as a character vector, cell array of block path names, or vector of block handles. For one block, specify the full path name of the block. For multiple blocks, specify either a cell array of block path names or a vector of block handles.

This function can create Bus objects from these blocks:

  • Bus Creator blocks

  • Subsystem Inport blocks

  • Subsystem Outport blocks

If you specify a block associated with a bus hierarchy, the function also creates Bus objects for all nested buses in the hierarchy.

Structure of objects or numeric structure, specified as a structure that can contain MATLAB timeseries, MATLAB timetable, and matlab.io.datastore.SimulationDatastore objects or a numeric structure.

Name of function being generated, specified as a character vector. The file name must be unique.

Format of function being generated, specified as either 'cell' or 'object'. The 'cell' format is more compact, but the 'object' format is easier to read.

The 'cell' format saves the Bus object definitions in a cell array of cell arrays and creates the Bus objects by calling Simulink.Bus.cellToObject. Each subordinate cell array represents a Bus object and contains these properties:

  1. Bus name

  2. Header file

  3. Description

  4. Data scope

  5. Alignment

  6. Preserve Element Dimensions

  7. Elements

The elements field is a cell array that contains this information for each of the Simulink.BusElement objects that the Bus object references:

  1. Element name

  2. Dimensions

  3. Data type

  4. Sample time — The cell array contains this field when the sample time is not inherited. A noninherited sample time causes an error during model compilation. For more information, see Simulink.BusElement objects no longer support the SampleTime property.

  5. Complexity

  6. Dimensions mode

  7. Minimum

  8. Maximum

  9. Units

  10. Description

The 'object' format saves the Bus object definitions as arrays. The function uses array indexing to access elements of the array and dot notation to assign property values.

Data dictionary, 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.

Output Arguments

collapse all

Bus object information, returned as a structure array.

When you specify blocks, each element of the busInfo structure array corresponds to one block and contains these fields:

  • block — Handle of the block

  • busName — Name of the Bus object associated with the block

When you use specify a struct, the busInfo structure contains these fields:

  • block — Empty matrix ([])

  • busName — Name of the Bus object that corresponds to the structure

Compatibility Considerations

expand all

Errors starting in R2020b

Introduced before R2006a