Variant Subsystem, Variant Model, Variant Assembly Subsystem

Template subsystem containing Subsystem, Model, or Subsystem Reference blocks as variant choices

• Library:

• Simulink / Ports & Subsystems

  HDL Coder / Ports & Subsystems

• 
• 
• 

Description

The Variant Subsystem block enables you to include multiple implementations of a component in a separate hierarchy.

For example, suppose you want to simulate a model that represents a vehicle with three possible engine configurations: 4-cylinder gas, 6-cylinder gas, and 8-cylinder gas. You could implement each engine model as a separate subsystem inside the Variant Subsystem and then switch between the subsystems based on the Types of Variant Control Modes in Variant Blocks you select. For more information, see Introduction to Variant Controls.

Note

Only one implementation of a Variant Subsystem is active during simulation.

The Variant Subsystem block is a template preconfigured to contain two or more blocks to use as Variant choices. These choices represent multiple implementations of a system. Only one child block is active during model execution. The active child block is referred to as the active variant.

Each variant choice inside the Variant Subsystem block is associated with a Variant control mode and a Variant activation time. The variant control mode determines how to select the active variant. The variant activation time determines a time to activate the choices and to decide whether to include only the active choice or both active and inactive choices in the generated code.

A Variant Subsystem block can contain a mixture of Subsystem blocks, Model blocks, or Subsystem Reference blocks as variant choices. A Variant Subsystem block with Model blocks as choices is called a Variant Model block. For more information, see Represent Variant Choices in a Variant Subsystem. A Variant Subsystem block that references model or subsystem files using Variant choices specifier is called a Variant Assembly Subsystem block.

Apart from the variant choices, you can include Inport, control port (Enable, Trigger, Reset, and Function-Call), Outport, or Connection Port (Simscape) blocks inside a Variant Subsystem block. There are no drawn connections between the blocks that are inside the Variant Subsystem blocks. Simulink^® automatically wires the active variant to the Inport and Outport blocks of the Variant Subsystem during model compilation. The blocks representing variant choices can have input and output ports that differ in number from the input and output ports in the parent Variant Subsystem block. For more information, Map Inports and Outports of Variant Choices in Variant Subsystem.

Using Variant Subsystem block allows you to:

• Mix Subsystem, Model, and Subsystem Reference blocks as variant choices.

• Model components that do not have similar interface. You can have different numbers of inports and outports for multiple variant choices inside a Variant Subsystem. However, the conditions listed in Map Inports and Outports of Variant Choices in Variant Subsystem must be met.

• Establish a hierarchical block diagram, where the Variant Subsystem block is on one layer and the variant choices are on another layer.

• Keeps functionally related blocks together.

• Reduce the complexity of your model.

• During model compilation, Simulink eliminates inactive blocks throughout the model, depending on the variant activation time you select.

The color and icon of the variant badge on the block icon changes depending on the values of the Variant activation time, Variant control mode, and Propagate conditions outside of variant subsystem parameters set on the block. For more information, see Variant Badges.

Variant Assembly Subsystem

A Variant Assembly Subsystem block enables you to add or remove its variant choices from external sources without modifying the model. A Variant Assembly Subsystem block can contain Model blocks, Subsystem Reference blocks, or both as its variant choices. Use the Variant choices specifier parameter to specify the variant choices without navigating inside the block. Unlike Variant Subsystem, you cannot manage the variant choices from inside the Variant Assembly Subsystem block.

To add Model or Subsystem Reference blocks as variant choices:

1. Maintain the model and subsystem files to be referenced on the MATLAB^® path.

2. Specify a valid MATLAB expression in the Variant choices specifier parameter that evaluates to a one-dimensional cell array of character vectors. Every cell in the array must either be a model file name or a subsystem file name. The cell can also contain a file name pattern that matches the model, or the subsystem file names as described in Specify Variant Choices of Variant Assembly Subsystem Block in Variant Choices Specifier Parameter. The Variant Assembly Subsystem block then adds the Model and Subsystem Reference blocks from the listed files as variant choices of the block.

For more information, see Add or Remove Variant Choices of Variant Assembly Subsystem Blocks Using External Files.

Note

To convert a Variant Subsystem block to a Variant Assembly Subsystem block, follow the steps in Convert Variant Subsystem to Variant Assembly Subsystem. After the conversion, all the choices are maintained in separate model or subsystem files with the same name as the choices.

Ports

During simulation, Simulink disables the inactive ports in a Variant Subsystem block.

Input

In_1 — Input port corresponding to root-level Inport blocks contained in Variant Subsystem

same data types accepted by Inport blocks

Each Subsystem, Model, or Subsystem Reference block contained within a Variant Subsystem represents one variant choice. The variant choices can contain Inport, control port (Enable, Trigger, Reset, and Function-Call), or Connection Port (Simscape) blocks at its input. The variant choices can have input ports that differ in number from the input ports in the parent Variant Subsystem block. However, the conditions described in Map Inports and Outports of Variant Choices in Variant Subsystem must be met.

Output

Out_1 — Output port corresponding to root-level Outport blocks contained in Variant Subsystem

same data types accepted by Outport blocks

Each Subsystem, Model, or Subsystem Reference block contained within a Variant Subsystem represents one variant choice. The variant choices can contain Outport or Connection Port (Simscape) blocks at its output. The variant choices can have output ports that differ in number from the output ports in the parent Variant Subsystem block. However, the conditions described in Map Inports and Outports of Variant Choices in Variant Subsystem must be met.

Note

The unconnected outports (inactive outports) of a Variant Subsystem outputs a ground value. To output a value other than ground, select the Specify output when source is unconnected parameter of the Outport block and specify a value.

Parameters

To access these parameters, right-click the variant badge on the block icon and select Block Parameters. For more information, see Variant Badges.

Main

Variant control mode — Variant control mode

expression (default) | label | sim codegen switching

The variant control that determines the active variant choice can be any of these types.

• expression — In expression mode, Simulink chooses the active variant based on the evaluation of the variant conditions. When a condition expression evaluates to true, the corresponding variant choice becomes active. When a condition expression evaluates to false, the corresponding variant choice becomes inactive. See Switch Between Choices Using Condition Expressions in Variant Blocks.

• label — In label mode, Simulink chooses the active variant based on the name of the variant. The variant control is a string and does not require you to create any variable in any workspaces. See Switch Between Choices Using Labels in Variant Blocks.

• sim codegen switching — To automatically switch between the variants for simulation and code generation workflows without creating any workspace variable, use sim codegen switching mode. When you simulate a model, Simulink automatically chooses the sim branch as the active choice. Similarly, when you do a software-in-the-loop (SIL) or processor-In-Loop (PIL) simulation, generate code, or use external mode, Simulink automatically chooses the codegen branch. This mode is not supported for models configured with an ERT-based system target file and service code interface. See Switch Between Choices for Simulation and Code Generation Workflows Without Using Control Variables in Variant Blocks.

For more information on variant control modes, see Introduction to Variant Controls. For a comparison between different types of variant control modes, see Compare Different Types of Variant Control Modes in Variant Blocks.

Dependencies

The availability of different variant activation times depends on the type of the Variant control mode that you specify. The Variant activation time parameter determines the time when Simulink sets the active choice. The parameter also determines which variability to include in the generated code. This table explains the variant activation time supported by each variant control mode.

Variant activation time
Variant control mode	update diagram	update diagram analyze all choices	code compile	startup
expression	✓	✓	✓	✓
label	✓	x	x	x
sim codegen switching	✓	✓	x	x

Programmatic Use

Block Parameter: VariantControlMode

Type: character vector

Values: expression | label | sim codegen switching |

Default: expression

Variant activation time — Time when Simulink chooses active variant choice

update diagram (default) | update diagram analyze all choices | code compile | startup | inherit from Simulink.VariantControl

This parameter determines which variability to include in the simulation and code generation workflows. For more information, see Activate Variant During Different Stages of Simulation and Code Generation Workflow.

You can set the Variant activation time parameter as:

• update diagram — When you execute the model, only the active choice is included in the simulation and the code generation workflow. Generated code contains only the active choice.

• update diagram analyze all choices — When you execute the model, both active and inactive choices are analyzed for consistency across the model. However, only the active choice is included in the simulation and the code generation workflow. Generated code contains only the active choice.

• code compile — When you execute the model, both active and inactive choices are analyzed for consistency across the model, and all choices are included in the simulation and the code generation workflow. Generated code contains both the active and inactive choices enclosed in the preprocessor conditionals #if and #elif. However, the executable built from the generated code contains only active choice.

• startup — When you execute the model, both active and inactive choices are analyzed for consistency across the model, and all choices are included in the simulation and the code generation workflow. With this option, you can improve the speed of iterative simulations using fast restart. For more information, see Run Iterative Simulations Without Recompiling Model for Variant Systems Using Fast Restart. Code generated from the model contains both the active and inactive choices that are enclosed in regular if conditions. The executable built from the generated code also contains both active and inactive choices.

• inherit from Simulink.VariantControl — When you execute the model, the block inherits the activation time from its variant control variables of type Simulink.VariantControl. If a variant block has multiple variant control variables of type Simulink.VariantControl, then all those variables must have the same activation time.

Dependencies

The availability of different variant activation times depends on the type of the variant control mode that you specify. The Variant activation time parameter determines when Simulink sets the active choice. The parameter also determines which variability to include in the generated code. This table explains the variant activation time supported by each variant control mode.

Variant activation time
Variant control mode	update diagram	update diagram analyze all choices	code compile	startup
expression	✓	✓	✓	✓
label	✓	x	x	x
sim codegen switching	✓	✓	x	x

Programmatic Use

Block Parameter: VariantActivationTime

Type: character vector

Values: update diagram | update diagram analyze all choices | code compile | startup

Default: update diagram

Variant choices (table of variant systems) — Table of variant choices, variant controls, and conditions

empty table (default)

The table has a row for each variant choice contained in the Variant Subsystem. If there are no variant choices, the table is empty.

You can use buttons to the left of the Variant choices table to modify the elements in the table.

To...	Click...
Create and add a new subsystem choice: Create a new Subsystem block as a variant choice and add an entry for the new choice in the table.
Create and add a new model variant choice: Create a new Model block as a variant choice and add an entry for the new choice in the table.
Create/Edit selected variant object: Create or edit a Simulink.Variant object in the global workspace and specify the variant condition using the Simulink.Variant object parameter dialog box. Note For a model that uses the base workspace, this operation creates the Simulink.Variant object in the base workspace and the object is available only for the current MATLAB session. To permanently store the data, save the object in a MAT file or MATLAB script.
Open selected variant choice block: Open the Subsystem block for the selected row.
Refresh dialog information from Variant Subsystem contents: Update the Variant choices table according to the variant choices and values of the variant control in the global workspace.

Dependencies

The Variant Assembly Subsystem block allows you to only open the selected variant choice and refresh the block dialog using this parameter. To add new variant choices to the Variant Assembly Subsystem block, use the Variant choices specifier parameter.

Name (read-only) — Variant choice name

Subsystem and Subsystem1 (default) | name of Subsystem or Model block contained in the Variant Subsystem

This read-only parameter displays the name of the blocks contained in the Variant Subsystem.

Variant control label — Name of choice in label mode

true or false (default) | string

A name for a choice, specified as a string.

Dependencies

To enable this parameter, set Variant control mode to label.

Variant control expression — Condition expression that determines the active choice

true or false (default) | boolean condition expression | a Simulink.Variant object representing a boolean condition expression | (default)

Specify the condition expression to determine the active choice. When a condition expression evaluates to true, Simulink activates the corresponding variant choice. When a condition expression evaluates to false, Simulink deactivates the corresponding variant choice.

The variant controls can be:

• Boolean condition expression for rapid prototyping. For example, A == 1, A ~= B, A && B == 1, and so on.

• A Simulink.Variant object that contains a condition expression for condition reuse. See Simulink.Variant Objects for Variant Condition Reuse of Variant Blocks.

• Default Variant Choice if none of the choices evaluates to true.

Here, A and B are operands called as variant control variables. ==, ~=, and && are operators in the condition expression. The condition expression can contain one or more such variant control variables and operators. For information on supported types and storage location of variant control variables, see Types of Variant Control Variables (Operands) in Variant Blocks and Storage Locations for Variant Control Variables (Operands) in Variant Blocks. For information on operators, see Types of Operators in Variant Blocks for Different Activation Times.

For more information, see Switch Between Choices Using Condition Expressions in Variant Blocks.

Programmatic Use

Structure field: Represented by the read-only variant.Name field in the Variant parameter structure

Type: character vector

Value: variant control that is associated with the variant choice

Default: 'variant'

Condition (read-only) — Condition expression in Simulink.Variant object

N/A (default)

This read-only field displays the condition expression specified as Simulink.Variant object. To change or edit the condition expression, use the Simulink.Variant parameter dialog box that appears when you double-click the object in the workspace.

Note

The operands that you specify in a condition expression of type Simulink.Variant must be defined in the base workspace or a data dictionary. Specifying operands that are defined in the mask or model workspace is not supported.

Label mode active choice — Name of active choice in label mode

true(Subsystem) (default) | false(Subsystem1)

This list contains the labels of all the variant choices. To set an active choice, select a label from the list. The corresponding choice becomes active. Alternatively, you can follow the approaches described in Set Active Choices Using Variant Control Labels to change the active choice in label mode.

Dependencies

To enable this parameter, set the Variant control mode parameter to label.

Programmatic Use

Parameter: LabelModeActivechoice

Type: character vector

Value: if no label mode active choice is specified, the value is empty. If label mode active choice is specified, the value is the name of the label mode active choice.

Default: ''

Allow zero active variant controls — Whether to allow zero active variant choices

off (default) | on

• off — Simulink generates an error when there is no active variant choice.

• on — When you select this option and if there is no active variant choice, Simulink simulates the model without any active variant choice in the Variant Subsystem. Simulink disconnects all the blocks connected to the input and output stream of Variant Subsystem block, thus removing the variant regions completely from the model. The inactive outports of the Subsystem output a ground value. To output a value other than ground, select the Specify output when source is unconnected parameter of the Outport block and specify a value of your choice.

Dependencies

This parameter is available only if there are no default variant choices in the Variant Subsystem and if you set Variant control mode to expression.

Programmatic Use

Parameter: AllowZeroVariantControls

Type: character vector

Value: 'off' | 'on'

Default: 'off'

Propagate conditions outside of variant subsystem — Option to choose if components outside of the Variant Subsystem must be informed of the active and inactive state of underlying blocks

off (default) | on

When you select the Propagate conditions outside of variant subsystem parameter, Simulink propagates the variant condition of the underlying blocks to the Variant Subsystem container block so the subsystem can adapt its interface to the state of the underlying blocks. Ports that are mapped to the ports on the active choice becomes active. Ports that are not mapped to the ports on the inactive choice becomes inactive. Selecting this option ensures that the components outside of the Variant Subsystem are aware of the active and inactive state of blocks within the Variant Subsystem block. For more information, see Propagate Variant Conditions Outside Variant Subsystems and Use Variant Subsystem Blocks with Conditionally Executed Subsystems

Note

Variant conditions do not propagate outside a Variant Subsystem block if all variant choices within the block have the same interface.

Programmatic Use

Parameter: PropagateVariantConditions

Type: character vector

Value: 'off' | 'on'

Default: 'off'

Reference

The parameters on the Reference tab enable you to add variant choices to a Variant Assembly Subsystem block. To access the parameters, you must convert the Variant Subsystem block to a Variant Assembly Subsystem block. For information on conversion, see Convert Variant Subsystem to Variant Assembly Subsystem.

Variant choices specifier — Model or subsystem file names as variant choices

any MATLAB expression that evaluates to a one-dimensional cell array of file names or file name patterns

To add Model or Subsystem Reference blocks as variant choices to a Variant Assembly Subsystem block, specify the corresponding model or subsystem file names. The file names must be specified as a MATLAB expression that returns a one-dimensional cell array of character vectors when evaluated. You can then validate the expression using the Validate button. On a successful validation, the blocks that correspond to the specified files are added as variant choices to the Variant Assembly Subsystem block. The file names of the newly added variant choices and their corresponding absolute paths are displayed in the Variant Choices table of the Reference tab.

To remove variant choices from a Variant Assembly Subsystem block, modify the expression specified in this parameter. You cannot manage the variant choices from inside the Variant Assembly Subsystem block.

The MATLAB expression that you specify must contain either of these:

• Model or subsystem file names that are on the search path of your current MATLAB session. For example, if you specify {'model1.slx', 'subsystemRef1.slx'} as a specifier, the blocks that correspond to the model1.slx and subsystemRef1.slx files are added as variant choices of the Variant Assembly Subsystem block.

• File name patterns that match the model or subsystem file names on the MATLAB path. The paths in the pattern can be absolute or relative to the parent folder of the model that contains the Variant Assembly Subsystem block. For example, if you specify {'folder_1/*.slx', 'folder_2/*.slx'} as a specifier, Simulink passes the character vectors folder_1/* and folder2/* to the dir function. The function then returns the model and the subsystem files that are located inside the folder1 and folder2 folders. The blocks that correspond to the returned files are added as variant choices of the Variant Assembly Subsystem block.

For information on how to add files or folders to the search path, see addpath.

For more information on how to specify choices in the Variant choices specifier parameter, see Add or Remove Variant Choices of Variant Assembly Subsystem Blocks Using External Files.

Programmatic Use

Parameter: VariantChoicesSpecifier

Type: character vector

Value: Any MATLAB expression that evaluate to a one-dimensional cell array of file names or file name patterns.

Default: ''

File — Names of files containing variant choices

empty (default)

This read-only parameter lists the names of the model or subsystem files that contain the variant choices of the block.

Path — Absolute paths of files containing variant choices

empty (default)

This read-only parameter lists the absolute paths of the model or subsystem files that contain the variant choices of the block.

Model Examples

Implement Variations in Separate Hierarchy Using Variant Subsystems

Learn basic functionality of variant subsystems.

Open Model

Variant Subsystem: Using Variant Subsystems for HDL Code Generation

2.4.3

Convert Variant Subsystem Block to Variant Assembly Subsystem Programmatically

Explains how to convert the Variant Subsystem block in a Simulink® model to a Variant Assembly Subsystem using the convertToVariantAssemblySubsystem method.

Open Live Script

Control Variant Choices in Masked Variant Assembly Subsystem Block Using Mask Parameter Object

Specify variant choices and set an active choice in a masked Variant Assembly Subsystem block using a mask parameter object.

Open Script

Block Characteristics

Data Types	Booleana | busa | doublea | enumerateda | fixed pointa | halfa | integera | singlea | stringa
Direct Feedthrough	no
Multidimensional Signals	yesa
Variable-Size Signals	yesa
Zero-Crossing Detection	no
a Actual data type or capability support depends on block implementation.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using Simulink® Coder™.

Actual data type or capability support depends on block implementation.

HDL Code Generation

Generate Verilog and VHDL code for FPGA and ASIC designs using HDL Coder™.

HDL Coder™ provides additional configuration options that affect HDL implementation and synthesized logic. Actual data type or capability support depends on block implementation.

HDL Architecture

Architecture	Description
Module (default)	Generate code for the subsystem and the blocks within the subsystem. HDL Coder generates code for all the variant choices.
BlackBox	Generate a black-box interface. That is, the generated HDL code includes only the input/output port definitions for the subsystem. In this way, you can use a subsystem in your model to generate an interface to existing manually written HDL code. The black-box interface generated for subsystems is similar to the interface generated for Model blocks, but without generation of clock signals.
No HDL	Remove the subsystem from the generated code. You can use the subsystem in simulation but treat it as a “no-op” in the HDL code.

Black Box Interface Customization

For the BlackBox architecture, you can customize port names and set attributes of the external component interface. See Customize Black Box or HDL Cosimulation Interface (HDL Coder).

HDL Block Properties

General
AdaptivePipelining	Automatic pipeline insertion based on the synthesis tool, target frequency, and multiplier word-lengths. The default is inherit. See also AdaptivePipelining (HDL Coder).
BalanceDelays	Detects introduction of new delays along one path and inserts matching delays on the other paths. The default is inherit. See also BalanceDelays (HDL Coder).
ClockRatePipelining	Insert pipeline registers at a faster clock rate instead of the slower data rate. The default is inherit. See also ClockRatePipelining (HDL Coder).
ConstrainedOutputPipeline	Number of registers to place at the outputs by moving existing delays within your design. Distributed pipelining does not redistribute these registers. The default is 0. For more details, see ConstrainedOutputPipeline (HDL Coder).
DistributedPipelining	Pipeline register distribution, or register retiming. The default is inherit. See also DistributedPipelining (HDL Coder).
DSPStyle	Synthesis attributes for multiplier mapping. The default is none. See also DSPStyle (HDL Coder).
FlattenHierarchy	Remove subsystem hierarchy from generated HDL code. The default is inherit. See also FlattenHierarchy (HDL Coder).
InputPipeline	Number of input pipeline stages to insert in the generated code. Distributed pipelining and constrained output pipelining can move these registers. The default is 0. For more details, see InputPipeline (HDL Coder).
OutputPipeline	Number of output pipeline stages to insert in the generated code. Distributed pipelining and constrained output pipelining can move these registers. The default is 0. For more details, see OutputPipeline (HDL Coder).
SharingFactor	Number of functionally equivalent resources to map to a single shared resource. The default is 0. See also Resource Sharing (HDL Coder).
StreamingFactor	Number of parallel data paths, or vectors, that are time multiplexed to transform into serial, scalar data paths. The default is 0, which implements fully parallel data paths. See also Streaming (HDL Coder).

Target Specification

This block cannot be the DUT, so the block property settings in the Target Specification tab are ignored.

Restrictions

• The DUT cannot be a Variant Subsystem.

Fixed-Point Conversion

Design and simulate fixed-point systems using Fixed-Point Designer™.

Actual data type or capability support depends on block implementation.

Version History

Introduced in R2010b