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 Implicit Bus-to-Vector Conversions

Blocks that do not accept buses may implicitly convert buses to vectors. When a bus is treated as a vector, bus elements become inaccessible.

Open and simulate the ex_bus_to_vector model.

model = 'ex_bus_to_vector';
load_system(model);
sim(model);
open_system(model);

The model simulates correctly, but the input to the Gain block is a bus, while the output is a vector. To accept the bus, the Gain blocks implicitly convert the bus to a vector.

To identify buses treated as vectors before simulation, use the Simulink.BlockDiagram.addBusToVector function.

blocks = Simulink.BlockDiagram.addBusToVector(model)

### 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

Explicitly Define Bus-To-Vector Conversions

To more easily identify unexpected conversions, specify acceptable bus-to-vector conversions with Bus to Vector blocks.

Open and simulate the ex_bus_to_vector model.

model = "ex_bus_to_vector";
load_system(model);
sim(model);
open_system(model);

The model 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.

To insert Bus to Vector blocks where blocks implicitly convert buses to vectors, use the Simulink.BlockDiagram.addBusToVector function with the third argument set to false.

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

model1 = 'ex_bus_to_vector_blocks';
save_system(model,model1)

[blocks,busToVectors] = ...
    Simulink.BlockDiagram.addBusToVector(model1,true,false)

### Processing block diagram 'ex_bus_to_vector_blocks'
### Number of blocks left that are connected to a bus being used as a vector: 2
### Successfully inserted Bus to Vector Blocks in model. Preparing to save model and/or libraries
### To eliminate modeling errors in the future, please enable strict bus modeling by setting the 'Bus signal treated as vector' diagnostic in the Configuration parameter dialog, Diagnostic/Connectivity tab to 'error'
### Done processing block diagram 'ex_bus_to_vector_blocks'

blocks=1×2 struct array with fields:
    BlockPath
    InputPort
    LibPath

busToVectors = 2x1 cell
    {'ex_bus_to_vector_blocks/Bus to Vector' }
    {'ex_bus_to_vector_blocks/Bus to Vector1'}

The Gain blocks no longer implicitly convert the buses to vectors. The inserted Bus to Vector blocks perform the conversions explicitly.

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. Check 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.

Version History

Introduced in R2007a