Main Content

Simulink.Bus.createObject

Create Simulink.Bus objects from blocks or MATLAB structures

collapse all in page

Syntax

busInfo = Simulink.Bus.createObject(mdl,busSource)
busInfo = Simulink.Bus.createObject(S)
busInfo = Simulink.Bus.createObject(___,file)
busInfo = Simulink.Bus.createObject(___,file,fileFormat)
busInfo = Simulink.Bus.createObject(S,file,fileFormat,scope)

Description

busInfo = Simulink.Bus.createObject(mdl,busSource) creates Simulink.Bus objects for the buses specified by busSource in the model specified by mdl. The function returns information about the created objects.

When the model uses a data dictionary, this function creates the objects in the data dictionary. Otherwise, this function creates the objects in the base workspace.

example

busInfo = Simulink.Bus.createObject(S) creates Simulink.Bus objects from the structure specified by S. The structure can contain MATLAB® timeseries, MATLAB timetable, and matlab.io.datastore.SimulationDatastore objects. The structure can be a numeric structure.

The function creates the objects in the base workspace.

example

busInfo = Simulink.Bus.createObject(___,file) saves the Simulink.Bus object definitions in a function. The name of the function is specified by file.

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

example

busInfo = Simulink.Bus.createObject(___,file,fileFormat), where fileFormat is "object", saves the Simulink.Bus object definitions using arrays. The "object" format makes the function easier to read. The default for fileFormat is "cell", which uses cell arrays and is more compact.

example

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

Examples

collapse all

Open Live Script

Create Simulink.Bus objects from a Bus Creator block that creates a bus with multiple levels of hierarchy.

Open the example model named BusHierarchy.

mdl = "BusHierarchy";
open_system(mdl)

BusHierarchy model with two Bus Creator blocks

Create a Simulink.Bus object from the Bus Creator block named Bus Creator1. This block receives input from a source block and another Bus Creator block.

block = "BusHierarchy/Bus Creator1";
busInfo = Simulink.Bus.createObject(mdl,block);

This command creates Simulink.Bus objects named TopBus and NestedBus in the base workspace. Each bus object represents a bus in the bus hierarchy.

To view the Simulink.Bus objects, open the Type Editor.

typeeditor

TopBus and NestedBus in the Type Editor

Open Live Script

Create Simulink.Bus objects from a bus element port, which Out Bus Element blocks represent.

Open the example model named BusOutput.

mdl = "BusOutput";
open_system(mdl)

BusOutput model

The output bus has multiple levels of hierarchy. The top-level bus contains a nested bus.

Create Simulink.Bus objects that define the bus hierarchy at the output port named OutBus.

port = "BusOutput/OutBus";
busInfo = Simulink.Bus.createObject(mdl,port);

To view the objects, open the Type Editor.

typeeditor
Open Live Script

Create Simulink.Bus objects from a Bus Creator block and save the Simulink.Bus object definitions in a function.

Open the example model named BusHierarchy. 

mdl = "BusHierarchy";
open_system(mdl);

BusHierarchy model with two Bus Creator blocks

Create Simulink.Bus objects from the Bus Creator block named Bus Creator1. This block receives input from a source block and another Bus Creator block. To save the Simulink.Bus object definitions in a function, also specify a filename.

block = "BusHierarchy/Bus Creator1";
file = "BusObjectFunction";
busInfo = Simulink.Bus.createObject(mdl,block,file);

These commands create Simulink.Bus objects named TopBus and NestedBus in the base workspace and a file named BusObjectFunction in your current folder.

To examine the file contents, open the file. By default, the file uses the "cell" format. For example, the Chirp element is defined by a cell array.

{'Chirp', 1, 'double', 'real', 'Sample', 'Fixed', [], [], '', ''};

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

file1 = "BusObjectFunctionFormatted";
busInfo1 = Simulink.Bus.createObject(mdl,block,file1,"object");

To examine the file contents, open the file. In the "object" format, the Chirp element is defined by an array that uses dot notation to assign property values.

elems(1) = Simulink.BusElement;
elems(1).Name = 'Chirp';
elems(1).Dimensions = 1;
elems(1).DimensionsMode = 'Fixed';
elems(1).DataType = 'double';
elems(1).Complexity = 'real';
elems(1).Min = [];
elems(1).Max = [];
elems(1).DocUnits = '';
elems(1).Description = '';
Open Live Script

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 Simulink.Bus objects that correspond with the structure.

busInfo = Simulink.Bus.createObject(bus_struct);

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

To view the objects, open the Type Editor.

typeeditor

Simulink.Bus objects named slBus1, A, C, and C2 in the Type Editor

Input Arguments

collapse all

Model name or handle, specified as a character vector or string scalar.

The model you specify must compile successfully.

Source of bus definition, specified as a character vector, string scalar, cell array of block paths, or vector of block handles.

This function can create Simulink.Bus objects from buses at these sources:

  • Bus Creator blocks

  • Input ports represented by In Bus Element blocks

  • Output ports represented by Out Bus Element blocks

  • Subsystem Inport blocks

  • Subsystem Outport blocks

When the bus has hierarchy, the function also creates Simulink.Bus objects for the nested buses in the bus hierarchy.

To specify a bus at a Bus Creator, Inport, or Outport block, use the corresponding block path or handle.

Example: Simulink.Bus.createObject(mdl,"BusHierarchy/Bus Creator") specifies one bus source via a block path.

Example: Simulink.Bus.createObject(mdl,{'BusHierarchy/Bus Creator','BusHierarchy/Bus Creator1'}) specifies multiple bus sources via a cell array of block paths.

Example: Simulink.Bus.createObject(mdl,[bc bc1]) specifies multiple bus sources via a vector of block handles.

To specify a bus at a port represented by an In Bus Element or Out Bus Element block, use the path to the port or element. For a port, the path is composed of the model name and port name. For an element of a port, the path is composed of the model name, port name, and one or more element names.

Example: Simulink.Bus.createObject(mdl,"BusOutput/OutBus") specifies the top-level bus of a root-level bus element port.

Example: Simulink.Bus.createObject(mdl,"BusOutput/OutBus.NestedBus") specifies a nested bus of a root-level bus element port.

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

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

Name of function being generated, specified as a character vector or string scalar. The filename 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 defines the Simulink.Bus object with a cell array of cell arrays and creates the objects by calling Simulink.Bus.cellToObject. Each subordinate cell array represents a Simulink.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 Simulink.Bus object references:

  1. Element name

  2. Dimensions

  3. Data type — When this field specifies a Simulink.Bus object, the specification does not include the Bus: prefix. This prefix is optional when you set the data type of a Simulink.BusElement object to a Simulink.Bus object.

  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. Sampling mode

  7. Dimensions mode

  8. Minimum

  9. Maximum

  10. Units

  11. Description

The "object" format defines the Simulink.Bus object with 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.

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

Output Arguments

collapse all

Bus object information, returned as a structure array.

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

  • block — Handle of the block

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

When you specify a structure or a bus at a bus element port, the busInfo structure contains these fields:

  • block — Empty matrix ([])

  • busName — Name of the Simulink.Bus object that corresponds to the structure or bus

Version History

Introduced before R2006a

expand all

See Also

Tools

Objects

Functions

Blocks

Topics