Main Content

Introduction to Variant Controls

The components of a Simulink® model that contain variants are activated or deactivated based on the variant choice that you select.

Each variant choice in your model is associated with a variant control. Variant controls determine which variant choice is active. By changing the value of a variant control, you can switch the active variant choice.

While each variant choice is associated with a variant control, only one variant control can evaluate to true. When a variant control evaluates to true, Simulink activates the variant choice that corresponds to that variant control.

You can specify variant controls of type expression, label or sim codegen switching for modeling variant blocks and variant parameters.

Variant control mode

You can specify the Variant control mode parameter as:

  • 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 and Variant Parameters.

  • 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 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. See Switch Between Choices For Simulation And Code Generation Workflows in Variant Blocks.

Switch Between Choices Using Condition Expressions in Variant Blocks and Variant Parameters

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.

You can use the expression type of variant controls in variant blocks and in variant parameters.

  • To specify the variant condition expressions in variant blocks:

    • Right-click the badge on the variant block, select Block Parameters, and then specify the variant condition expression in the Variant control expression parameter of the block parameter dialog box.

       Variant control mode: expression

    • Programmatically, by using this command:

      set_param('set_param('choiceName', 'VariantControl', 'A == 1')
      where choiceName is the full path of the variant choice, and A == 1 is the expression associated with the variant choice.

  • To specify the variant condition expressions in variant parameter, use the Simulink.VariantVariable object. Fore more information, see Create a Simple Variant Parameter Model.

The variant controls can be:

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 Condition Expressions and Storage Locations for Variant Control Variables (Operands) in Variant Condition Expressions. For information on operators, see Operators in Variant Condition Expressions.

Note

You can simulate and generate code from the model containing a variant block with Variant control mode set to expression mode.

Types of Variant Control Variables (Operands) in Variant Condition Expressions

In expression mode, you can specify the variant control variables as any of these types—from options to use while prototyping to options required for generating code from your model.

SpecificationPurposeExample
Simulink.VariantControlAssociate a variant activation timeA == 1, where A is a Simulink.VariantControl object. See Variant Control Variables Objects to Associate an Activation Time in Variant Blocks and Scalar Values for Rapid Prototyping of Variant Parameters.
Scalar variableRapid prototyping

A == 1, where A is a scalar variable. See Scalar Variables for Rapid Prototyping in Variant Blocks.

Note

Scalar variables as variant control variables are not supported in variant parameters.

Simulink.Parameter objectGenerate preprocessor conditionals for code generationVssmode == 1, where Vssmode is a Simulink.Parameter object. See, Simulink.Parameter Objects with Integer for Code Generation in Variant Blocks and Simulink.Parameter Objects for Code Generation of Variant Parameters.
Simulink EnumerationsImproved code readability because condition values are represented as meaningful names instead of integersLEVEL == Level.Advanced, where Level is an integer-based enumeration class and Advanced is the enumerated value. See, Enumerated Types To Improve Code Readability of Variant Blocks and Enumerated Types to Improve Code Readability of Variant Parameters.
Simulink.Variant objectReuse variant conditionsLinearController == 1, where LinearController is a Simulink.Variant object that encapsulates the condition expression FUEL==2 && EMIS==1. See, Simulink.Variant Objects for Variant Condition Reuse in Variant Blocks and Simulink.Variant Objects for Variant Condition Reuse of Variant Parameters.

Storage Locations for Variant Control Variables (Operands) in Variant Condition Expressions

You can define the variant control variables in different storage locations based on your requirement.

Note

All the variant control variables in a variant block or in a variant parameter must originate from the same storage location.

Define variant control variables:

InToSupported types of variant control variables (See Types of Variant Control Variables (Operands) in Variant Condition Expressions)For more information
Base workspaceStore variables while you experiment with temporary modelsScalar variables, Simulink.VariantControl, Simulink.Variant, Simulink.Parameter, and enumerated typeTemporary Data: Base Workspace
Mask workspacePermanently store data that is local to the mask of a block.Scalar variables, Simulink.VariantControl, and enumerated typeApproaches to Control Active Variant Choice of a Variant Block Using Mask or Model Workspace
Model workspacePermanently store data that is local to a modelScalar variables, Simulink.VariantControl, and enumerated typeApproaches to Control Active Variant Choice of a Variant Block Using Mask or Model Workspace
Data DictionaryPermanently store global data, share data between models, and track changes made to data.Scalar variables, Simulink.VariantControl, Simulink.Variant, Simulink.Parameter, and enumerated typeWhat Is a Data Dictionary?

For capabilities and advantages of each storage location, see Determine Where to Store Variables and Objects for Simulink Models

Operators in Variant Condition Expressions

Variant condition expressions can contain MATLAB® operators, provided the expression evaluates to a boolean value.

 Supported Operators in Variant Blocks

 Supported Operators in Variant Parameters

Evaluate Variant Condition Expressions at Different Variant Activation Times

The expression mode supports update diagram, update diagram analyze all choices, code compile, and startup activation times. For more information on variant activation times, see Activate Variant During Different Stages of Simulation and Code Generation Workflow.

Automatically Identify Variant Regions Using Variant Condition Propagation

Simulink determines the model components that are active during simulation by the process of variant condition propagation. This process evaluates the variant controls specified on the variant blocks and automatically propagates the variant conditions to the connecting blocks. Variant conditions can propagate through signal lines, buses, and function calls to reach other blocks in the model. The process deactivates the model components associated with the inactive choices and they do not participate in simulation. You can stop condition propagation to define variant regions in the model.

You can use the Variant Conditions Legend to visualize the propagated variant conditions that activate each variant choice. Simulink annotates model components if there are variant conditions on them, and the Variant Conditions Legend displays the condition that corresponds to each annotation.

For more information, see Variant Condition Propagation Overview.

Switch Between Choices Using Labels in Variant Blocks

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 variable in any workspaces.

To specify the labels for choices in variant blocks, right-click the badge on the variant block, select Block Parameters, and then specify the labels in the Variant control label parameter of the block parameter dialog box.

 Variant control mode: label

Note

You cannot associate a label type of variant control with a variant parameter.

In label mode, the activation time of the variant block is set to update diagram by default. In other words, when you simulate a model, Simulink determines the active choice in the model compilation stage and generates the code only for the choice. See, Activate Variant During Different Stages of Simulation and Code Generation Workflow.

You can only simulate the model containing a variant block with Variant control mode set to label mode. Code generation is not supported.

Approaches to Set Active Choices Using Variant Control Labels

You can follow any of these approaches to set active choices in label mode:

  • Specify a name for each variant choice in the Variant control label parameter of the variant block dialog box. All the names that you specify are listed in the Label mode active choice drop-down. The label that you select from the list becomes the active choice.

  • Right-click the badge on the variant block and select Label Mode Active Choice.

  • From the mask workspace of the variant block using the initialization code. The active choice you specify in the mask initialization code overrides the active choice you specify using the Label mode active choice drop-down or the Label Mode Active Choice menu item. For more information, see Mask a Variant Subsystem.

  • Programmatically, by using this command:

    set_param(blockName,'LabelModeActiveChoice', 'variantChoiceLabel')
    where blockName is the name of the variant block and variantChoiceLabel is the label associated with the variant choice.

Switch Between Choices For Simulation And Code Generation Workflows in Variant Blocks

To automatically switch between the choices for simulation and code generation workflows without creating any workspace variable, use sim codegen switching variant control mode.

To specify simulation and code generation branches for variant choices, right-click the badge on the variant block, select Block Parameters, and then specify the (sim) and (codegen) keywords in the Variant control switch parameter of the block parameter dialog box.

When you simulate (Normal , Accelerator, Rapid Accelerator) a model, Simulink automatically chooses the (sim) branch as the active choice. Similarly, when you do a Software-in-the-loop (SIL), Processor-In-Loop (PIL) simulation or generate code or use external mode, Simulink automatically chooses the (codegen) branch. The code is generated only for the active choice. Inactive choices are not included in the generated code. In this mode, you can at most have only two choices in the variant block.

 Variant control mode: sim codegen switching

Note

You cannot associate a sim codegen switching type of variant control with a variant parameter.

In sim codegen switching mode, only the update diagram and the update diagram analyze all choices activation times are supported. In other words, when you simulate or generate code from a model, Simulink determines the active choice in the model compilation stage and generates the code only for the choice. See, Activate Variant During Different Stages of Simulation and Code Generation Workflow.

Compare Different Types of Variant Control Modes

This table explains the capabilities of different variant control modes to help you choose one that caters to your requirement.

Variant control modeCapabilities

expression— 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.

Use expression mode to:

label— 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 variable in any workspace.

Use label mode to:

  • Only simulate a model. No requirement to generate code from the model.

  • Control active choices without creating any workspace variables.

sim codegen switching— When you simulate (Normal , Accelerator, Rapid Accelerator) a model, then Simulink automatically chooses the sim branch as the active choice. Similarly, when you do a Software-in-the-loop (SIL), Processor-In-Loop (PIL) simulation or generate code or use external mode, Simulink automatically chooses the codegen branch.

Use sim codegen switching switching mode to:

  • To automatically switch between the choices for simulation and code generation workflows without creating any workspace variables.

  • Generate code only for active choice in the model.

Variant Activation Times for Different Variant Control Modes

The availability of different variant activation times depends on the type of the Variant control mode that you specify. The variant activation time determines the time when Simulink sets the active choice. The variant activation time also determines which variability to include in the generated code. For more information on variant activation times, see Activate Variant During Different Stages of Simulation and Code Generation Workflow.

This table explains the variant activation time supported by each variant control mode.

Variant activation time
Variant control mode update diagramupdate diagram analyze all choicescode compilestartup
expression
labelxxx
sim codegen switchingxx

Approaches for Specifying Variant Control Variables

This section explains how to use different types of variant control variables in variant condition expressions.

Variant Control Variables Objects to Associate an Activation Time in Variant Blocks

Simulink.VariantControl object enables you to associate a variant activation time with a variant control variable. You can define Simulink.VariantControl type of control variables in storage locations as listed in Storage Locations for Variant Control Variables (Operands) in Variant Condition Expressions.

Consider a model that contains a Variant Subsystem block with two variant choices, Linear Controller and NonLinear Controller subsystems.

  1. In the block parameters dialog box of the Variant Subsystem block, specify variant controls, V ==1 and V==2.

  2. In the base workspace, define a variant control variable object, V, using Simulink.VariantControl, set its value to 1, and then simulate the model. During simulation, the Linear Controller variant choice becomes active.

    V = Simulink.VariantControl('Value', 1, ActivationTime, 'update diagram analyze all choices')

    Note

    The Variant activation time that you specify in the block parameter dialog box overrides the ActivationTime that you specify in the Simulink.VariantControl object.

    Similarly, if you change the value of V to 2, the Nonlinear Controller variant choice becomes active.

    V.Value = 2;

Scalar Variables for Rapid Prototyping in Variant Blocks

Scalar MATLAB variant control variables allow you to rapidly prototype variant choices when you are still building your model. They help you focus more on building your variant choices than on developing the expressions that activate those choices. You can define scalar control variables in storage locations as listed in Storage Locations for Variant Control Variables (Operands) in Variant Condition Expressions.

Consider a model that contains a Variant Subsystem block with two variant choices, Linear Controller and NonLinear Controller subsystems.

  1. In the block parameters dialog box of the Variant Subsystem block, specify variant control in their simplest form as scalar variables, V ==1 and V==2.

  2. In the base workspace, define a variant control variable, V, set its value to 1, and then simulate the model. During simulation, the Linear Controller variant choice becomes active.

    V = 1;

    Similarly, if you change the value of V to 2, the Nonlinear Controller variant choice becomes active.

    V = 2;

Simulink.Parameter Objects with Integer for Code Generation in Variant Blocks

If you intend to generate code for a model containing variant choices, specify variant control variables as Simulink.Parameter objects. Simulink.Parameter objects allow you to specify other attributes (such as data type) that are required for generating code.

Note

You can define a variant control variable of type Simulink.Parameter only in the base workspace or in a data dictionary. Defining a variant control variable of type Simulink.Parameter in the mask or model workspace is not supported. For more information on storage locations for variant control variables, see Storage Locations for Variant Control Variables (Operands) in Variant Condition Expressions.

Simulink.Parameter objects within structures and that have data types other than Simulink.Bus objects are not supported.

Consider a model that contains a Variant Subsystem block with two variant choices, Linear Controller and NonLinear Controller subsystem.

  1. In the base workspace, define a Simulink.Parameter object, VssMode.

    VssMode = Simulink.Parameter;
    VssMode.Value = 1;
    VssMode.DataType = 'int32';
    VssMode.CoderInfo.StorageClass = 'Custom';
    VssMode.CoderInfo.CustomStorageClass = 'ImportedDefine';
    VssMode.CoderInfo.CustomAttributes.HeaderFile ='rtwdemo_importedmacros.h';

    Variant control variables defined as Simulink.Parameter objects can have one of these storage classes:

    • Define or ImportedDefine with header file specified

    • CompilerFlag

    • SystemConstant (AUTOSAR)

    • Your own storage class that defines data as a macro

    For more information about these storage classes, see Choose Storage Class for Controlling Data Representation in Generated Code (Simulink Coder).

    You can also convert a scalar variant control variable into a Simulink.Parameter object. For more information, see Convert Variant Control Variables into Simulink.Parameter Objects.

  2. Specify the Simulink.Parameter object as the variant control variable in the block parameters dialog box of the Variant Subsystem block, and then simulate the model. During simulation, the Linear Controller variant choice becomes active.

Enumerated Types To Improve Code Readability of Variant Blocks

Use enumerated types to give meaningful names to integers used as variant control values. You can define variant control variables of enumerated types in storage locations as listed in Storage Locations for Variant Control Variables (Operands) in Variant Condition Expressions.

Consider a model that contains a Variant Subsystem block with two variant choices, Linear Controller and NonLinear Controller subsystems.

  1. In the base workspace, define the classes that map enumerated values to meaningful names.

    Here, sldemo_mrv_CONTROLLER_TYPE is an integer-based enumeration class that is derived from the built-in data type, int32. The class has two enumeration values, Linear and NonLinear. These enumerated values have underlying integer values 0 and 1.

    classdef sldemo_mrv_CONTROLLER_TYPE < Simulink.IntEnumType
            enumeration
            Linear (1)
            NonLinear (2)
            end
    end
    
  2. Specify the names as variant control variables in the block parameters dialog box of the Variant Subsystem block.

  3. Define the Simulink.VariantControl object, E_Ctrl in the base workspace, specify its value as 1 and then simulate the model. During simulation, the Linear Controller variant choice becomes active.

    E_Ctrl.Value=1

Simulink.Variant Objects for Variant Condition Reuse in Variant Blocks

After identifying the variant choices that your model requires, you can construct complex variant conditions to control the activation of your variant choices by defining variant conditions as Simulink.Variant objects. Simulink.Variant objects enable you to reuse common variant conditions across models and help you encapsulate complex variant condition expressions.

You can specify the whole of a variant condition expression or only the variant control variable inside the condition expression of type Simulink.Variant.

Note

You can define a variant control variable of type Simulink.Variant only in the base workspace or in a data dictionary. Defining a variant control variable of type Simulink.Variant in the mask or model workspace is not supported. For more information on storage locations for variant control variables, see Storage Locations for Variant Control Variables (Operands) in Variant Condition Expressions.

Simulink.Variant within structures are not supported.

Consider a model that contains a Variant Subsystem block with two variant choices, Linear Controller and NonLinear Controller subsystem.

  1. In the base workspace, encapsulate variant control expressions as Simulink.Variant objects.

    Linear=Simulink.Variant('V==1');
    NonLinear=Simulink.Variant('V==2');
  2. Specify the Simulink.Variant objects as the variant control variables in the block parameters dialog box of the Variant Subsystem block.

    The Condition (read-only) parameter displays the encapsulated variant conditions.

  3. Define the Simulink.VariantControl object, V in the base workspace, specify its value as 1 and then simulate the model. During simulation, the Linear Controller variant choice becomes active.

    V.Value = 1;

Using this approach, you can develop complex variant condition expressions that are reusable.

Scalar Values for Rapid Prototyping of Variant Parameters

Scalar MATLAB® variables allow you to rapidly prototype variant values when you are still building your model. They help you focus more on building your variant values than on developing the expressions that activate those choices.

You can define scalar control variables in locations listed in Storage Locations for Variant Control Variables (Operands) in Variant Condition Expressions.

In the MATLAB Editor, specify variant choices in their simplest form as scalar variables in a Simulink.VariantVariable object.

vpObj = Simulink.VariantVariable('Choices',{'VCtrl==1', 1000, 'VCtrl==2', 2000})
vpObj = 
VariantVariable with 2 choices:

 Condition 	Value
__________	_____
VCtrl == 1	1000
VCtrl == 2	2000

Specification: ''

Use getChoice, setChoice, addChoice, removeChoice to access, modify, add or
remove choices

Activate one of the variant values by defining a control variable, VCtrl, and setting its value to 1 in a Simulink.VariantControl object. This condition activates the value 1000 and assigns this value to vpObj.

VCtrl = Simulink.VariantControl('Value', 1, 'ActivationTime', 'update diagram')
VCtrl = 
  VariantControl with properties:

             Value: 1
    ActivationTime: 'update diagram'

If you change the value of VCtrl to 2, Simulink® sets the value of vpObj to 2000.

VCtrl.Value = 2;

Simulink.Parameter Objects for Code Generation of Variant Parameters

If you intend to generate code for a model containing variant parameter values, specify variant control variables as MATLAB® variables or Simulink.Parameter objects. Simulink.Parameter objects allow you to specify other attributes (such as data type) that are required for generating code.

Note:

  • You can define a variant control variable of type Simulink.Parameter only in the base workspace or in a data dictionary. Defining Simulink.Parameter type of variant control variables in the mask or model workspace is not supported. For more information on storage locations for variant control variables, see Storage Locations for Variant Control Variables (Operands) in Variant Condition Expressions.

  • Simulink.Parameter objects within structures and that have data types other than Simulink.Bus objects are not supported.

In the MATLAB Editor, define a Simulink.Parameter object.

VSSMODE = Simulink.Parameter;
VSSMODE.Value = 1;
VSSMODE.DataType = 'int32';
VSSMODE.CoderInfo.StorageClass = 'Custom';
VSSMODE.CoderInfo.CustomStorageClass = 'ImportedDefine';
VSSMODE.CoderInfo.CustomAttributes.HeaderFile ='rtwdemo_importedmacros.h';

Variant control variables defined as Simulink.Parameter objects can have one of these storage classes:

  • Define or ImportedDefine with header file specified

  • CompilerFlag

  • SystemConstant (AUTOSAR)

  • Your own storage class that defines data as a macro

You can also convert a scalar variant control variable into a Simulink.Parameter object. For more information, see Convert Variant Control Variables into Simulink.Parameter Objects.

Specify the object as a variant control using a Simulink.VariantVariable object.

vpObj = Simulink.VariantVariable('Choices', {'VCtrl == 1',1000,'VCtrl == 2',2000});

Activate one of the variant values by defining a control variable VCtrl and setting its value to VSSMODE in a Simulink.VariantControl object. This condition activates the value 1000 and assigns this value to vpObj.

VCtrl = Simulink.VariantControl('Value',VSSMODE,'ActivationTime','code compile')
VCtrl = 
  VariantControl with properties:

             Value: [1x1 Simulink.Parameter]
    ActivationTime: 'code compile'

Enumerated Types to Improve Code Readability of Variant Parameters

Use enumerated types to give meaningful names to integers used as variant control values.

You can define variant control variables of enumerated types in storage locations as listed in Storage Locations for Variant Control Variables (Operands) in Variant Condition Expressions.

In the MATLAB® Editor, define the classes that map enumerated values to meaningful names.

Here, EngType is an integer-based enumeration class that is derived from the built-in data type, int32. The class has two enumeration values, Small and Big. These enumerated values have underlying integer values 1 and 2.

type EngType.m
classdef EngType < Simulink.IntEnumType
        enumeration
        Small (1)
        Big (2)
        end
end

Specify the names as variant choices in a Simulink.VariantVariable object.

vpObj = Simulink.VariantVariable('Choices', {'VCtrl == EngType.Small',3.5,'VCtrl == EngType.Big',8.5})
vpObj = 
VariantVariable with 2 choices:

       Condition       	Value
______________________	_____
VCtrl == EngType.Big  	8.5000
VCtrl == EngType.Small	3.5000

Specification: ''

Use getChoice, setChoice, addChoice, removeChoice to access, modify, add or
remove choices

Activate one of the variant values by defining the control variable VCtrl and setting its value to EngType.Small in a Simulink.VariantControl object. This condition activates the value 3.5 and assigns this value to vpObj.

Note: For a variant control variable object with 'startup' activation time, specifying a value of enumerated type is not supported.

VCtrl = Simulink.VariantControl('Value',EngType.Small,'ActivationTime','code compile')
VCtrl = 
  VariantControl with properties:

             Value: Small
    ActivationTime: 'code compile'

Using enumerated types simplifies the generated code because it contains the names of the values rather than integers.

Simulink.Variant Objects for Variant Condition Reuse of Variant Parameters

After identifying the variant values that your model requires, you can construct complex variant conditions to control the activation of your variant parameter values by defining variant conditions as Simulink.Variant objects. Simulink.Variant objects enable you to reuse common variant conditions across models and help you encapsulate complex variant condition expressions.

Note:

In the MATLAB® Editor, encapsulate variant control expressions as Simulink.Variant objects.

LinearController=Simulink.Variant('VCtrl==1');
NonLinearController=Simulink.Variant('VCtrl==2');

Specify the Simulink.Variant objects as the variant controls in a Simulink.VariantVariable object.

vpObj = Simulink.VariantVariable('Choices',{'LinearController',1000,'NonLinearController',2000})
vpObj = 
VariantVariable with 2 choices:

     Condition     	Value
___________________	_____
LinearController   	1000
NonLinearController	2000

Specification: ''

Use getChoice, setChoice, addChoice, removeChoice to access, modify, add or
remove choices

Activate one of the variant values by defining a control variable, VCtrl, and setting its value to LinearController in a Simulink.VariantControl object. This condition activates the value 1000 and assigns this value to vpObj.

VCtrl = Simulink.VariantControl('Value',1,'ActivationTime','update diagram')
VCtrl = 
  VariantControl with properties:

             Value: 1
    ActivationTime: 'update diagram'

Using this approach, you can develop complex variant condition expressions that are reusable.

Related Examples

More About