Simulink.BlockDiagram.addBusToVector

Convert virtual bus signals into vector signals by adding Bus to Vector blocks

Syntax

[destBlocks,busToVectorBlocks,ignoredBlocks] = Simulink.BlockDiagram.addBusToVector(model)

[destBlocks,busToVectorBlocks,ignoredBlocks] = Simulink.BlockDiagram.addBusToVector(model,includeLibs)

[destBlocks,busToVectorBlocks,ignoredBlocks] = Simulink.BlockDiagram.addBusToVector(model,includeLibs,reportOnly)

[destBlocks,busToVectorBlocks,ignoredBlocks] = Simulink.BlockDiagram.addBusToVector(model,includeLibs,reportOnly,strictOnly)

Description

[destBlocks,busToVectorBlocks,ignoredBlocks] = Simulink.BlockDiagram.addBusToVector(model) searches a model, excluding any library blocks, for bus signals used implicitly as vectors, and returns the results of the search.

[destBlocks,busToVectorBlocks,ignoredBlocks] = Simulink.BlockDiagram.addBusToVector(model,includeLibs) searches a model, and if includeLibs is true, includes in the search library blocks for bus signals used implicitly as vectors.

[destBlocks,busToVectorBlocks,ignoredBlocks] = Simulink.BlockDiagram.addBusToVector(model,includeLibs,reportOnly) searches a model, and if reportOnly is set to false, then the function inserts a Bus to Vector block into each bus that is used as a vector in any block that it searches. The insertion replaces the implicit use of a bus as a vector with an explicit conversion of the bus to a vector. The source and destination blocks of the signal do not change.

If Simulink.BlockDiagram.addBusToVector adds Bus to Vector blocks to the model or any library, the function changes the saved copy of the diagram.

If Simulink.BlockDiagram.addBusToVector changes a library block, the change affects every instance of that block in every model that uses the library.

[destBlocks,busToVectorBlocks,ignoredBlocks] = Simulink.BlockDiagram.addBusToVector(model,includeLibs,reportOnly,strictOnly) searches a model, and if strictOnly is true, the function checks for input bus signals used implicitly as vectors that are fed into one of these blocks. These blocks cannot take virtual bus signals, but they can accept nonvirtual bus signals:

• Delay

• Selector

• Assignment

• Vector Concatenate

• Reshape

• Permute Dimensions

Examples

Identify Bus-To-Vector Conversions

Model ex_bus_to_vector simulates correctly, but the input to the Gain block is a bus, while the output is a vector. The Gain block implicitly converts the bus to a vector.

Open the model.

open_system(fullfile(matlabroot,'examples','simulink','main',...
'ex_bus_to_vector'))

Identify buses treated as vectors.

[blocks] = Simulink.BlockDiagram.addBusToVector(...
'ex_bus_to_vector')

### Processing block diagram 'ex_bus_to_vector'
### Number of blocks left that are connected to a bus being used as a vector: 2
### Done processing block diagram 'ex_bus_to_vector'

blocks = 

  1×2 struct array with fields:

    BlockPath
    InputPort
    LibPath

To understand the relationship between Simulink.BlockDiagram.addBusToVector and the Bus signal treated as vector configuration parameter, see Manage Bus-to-Vector Conversions.

Add Bus to Vector Blocks

Model ex_bus_to_vector simulates correctly, but the input to the Gain block is a bus, while the output is a vector. The Gain block implicitly converts the bus to a vector.

Open the model.

open_system(fullfile(matlabroot,'examples','simulink','main',...
'ex_bus_to_vector'))

Insert Bus to Vector blocks.

When you use function Simulink.BlockDiagram.addBusToVector with reportOnly set to false, the function saves the model. To create a writable copy of model ex_bus_to_vector, this example uses the save_system function.

save_system('ex_bus_to_vector','ex_bus_to_vector_blocks');
[blocks,busToVectors] = Simulink.BlockDiagram.addBusToVector(...
'ex_bus_to_vector_blocks',true,false);

The Gain block no longer implicitly converts the bus to a vector. The inserted Bus to Vector block performs the conversion explicitly. The Bus to Vector block is virtual and does not affect simulation results, code generation, or performance.

To understand the relationship between Simulink.BlockDiagram.addBusToVector and the Bus signal treated as vector configuration parameter, see Manage Bus-to-Vector Conversions.

Input Arguments

model — Model name or handle

character vector | string scalar | numeric scalar

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

Data Types: double | char | string

includeLibs — Search library blocks

false (default) | true

Search library blocks, specified as false or true.

• false — Search only the blocks in the model.

• true — Search library blocks for bus signals used implicitly as vectors.

Specify as the second argument.

Data Types: logical

reportOnly — Report results without changing model

true (default) | false

Choice to report results without changing the model, specified as false or true.

• false — Update the model by inserting Bus to Vector blocks for bus signals that are implicitly used as vectors.

• true — Report search results, but do not change the model.

Specify as the third argument. Also specify the model and includeLibs arguments.

Data Types: logical

strictOnly — Check input bus signals used implicitly as vectors that feed blocks that can accept nonvirtual, but not virtual, bus signals

false (default) | true

Check input bus signals used implicitly as vectors that feed blocks that can accept nonvirtual, but not virtual, bus signals, specified as false or true. If strictOnly is true, the function checks for input bus signals used implicitly as vectors that are fed into one of these blocks. These blocks cannot take virtual bus signals, but they can accept nonvirtual bus signals.

• Delay

• Selector

• Assignment

• Vector Concatenate

• Reshape

• Permute Dimensions

Specify as the fourth argument. You must also specify the model, includeLibs, and reportOnly arguments.

Data Types: logical

Output Arguments

destBlocks — Blocks connected to buses but that treat buses as vectors

array of structures

Blocks connected to buses that treat buses as vectors, returned as an array of structures. Each structure in the array contains these fields:

• BlockPath — Character vector specifying the path to the block to which the bus connects.

• InputPort — Integer specifying the input port to which the bus connects.

• LibPath — If the block is a library block instance, and if includeLibs is true, the field value is the path to the source library block. Otherwise, LibPath is empty ([]).

busToVectorBlocks — Bus to Vector blocks added by function

cell array

Bus to Vector blocks added by function, specified as a cell array. If reportOnly is set to false, the cell array contains the paths to each Bus to Vector block that the function added to replace buses used as vectors. Otherwise, busToVectorBlocks is empty ([]).

ignoredBlocks — Cases where function cannot insert Bus to Vector block

array of structures

Cases where function cannot insert Bus to Vector block, specified as an array of structures. Each structure in the array contains these fields:

• BlockPath — Character vector specifying the path to the block to which the bus connects.

• InputPort — Integer specifying the input port to which the bus connects.

These cases occur when a Bus to Vector cannot be inserted because the input virtual bus signal consists of elements with mixed attributes.

Tips

• Before you execute this function:

  1. Ensure that the model compiles without error.

  2. Save the model.

• Back up the model and any libraries before calling the function with reportOnly set to false.

• To preview the effects of the change on blocks in all models, call Simulink.BlockDiagram.addBusToVector with includeLibs set to true and reportOnly set to true. Then, examine the information returned in the destBlocks output argument.