Variant Control Modes in Variant Blocks

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. For a simple example, see Introduction to Variant Controls.

Types of Variant Control Modes in Variant Blocks

These are types of variant control modes in Simulink:

Types of variant control modes with examples. In expression mode, variant control can be a boolean condition expression, a Simulink.VariantExpression object, or a default variant choice. In label mode, variant control is a string, and in sim codegen switching mode, variant controls are (sim) and (codegen) keywords.

Switch Between Choices Using Condition Expressions in Variant Blocks

In expression mode, Simulink chooses the active variant choice based on the evaluation of a logical condition called variant control expression. Only the variant choice whose control expression evaluates to true becomes active. These expressions are evaluated at specific phases of simulation or code generation, as specified by the variant activation time, so that the appropriate variant is selected for execution. You can specify variant control expressions in variant blocks and in variant parameters.

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.

Note

You can simulate and generate code from the model containing a variant block with Variant control mode set to expression mode. The generated code can contain active and inactive choices that are enclosed in preprocessor conditionals #if and #elif, or regular if conditions.

Use expression Type of Variant Control in Variant Blocks

To specify the variant condition expressions in variant blocks:

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

     Variant control mode: expression

  • Use this command.

    set_param('Model/Controller/Linear Controller',...
 'VariantControl', 'VSS_MODE == 1')
    In this command, Model/Controller/Linear Controller is the full path of the variant choice, and VSS_MODE == 1 is the expression associated with the variant choice in the model Model.

Types of Variant Controls in expression Mode

The variant controls can be:

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

  • A Simulink.VariantExpression object that contains condition expressions. Use Simulink.VariantExpression objects if you need to reuse a complex variant condition expression across multiple variant blocks and variant parameters, and use them for AUTOSAR code generation workflows. See Use Simulink.VariantExpression Objects for Variant Condition Reuse of Variant Blocks.

  • A default variant control if none of the other variant choices evaluate to true. You can specify at most one variant choice as the default for the block. During simulation, if none of the variant controls evaluate to true, Simulink uses the default variant as the active variant choice. To set a variant choice as the default, select the (default) keyword in the Variant control expression column for that choice.

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. For information on operators, see Types of Operators in Variant Blocks for Different Activation Times.

Note

  • A Variant Assembly Subsystem block does not support the Simulink.VariantExpression object type of variant control variable.

  • To comment out a variant control, place a % symbol before the variant control expression. During simulation, if the corresponding variant choice becomes active, Simulink ignores the variant choice. However, Simulink continues to execute any block callbacks inside the commented out variant choice.

Structure of a Variant Control Expression in Variant Blocks

A variant control expression consists of:

  • Variant control variables — Named variables defined in locations such as the base workspace, model workspace, or a data dictionary.

  • Operators — MATLAB® operators such as logical operators (&&, ||, ~) and relational operators (==, ~=, <, >) to combine or compare variant control variables and constants. The types of operators you can use depend on the Variant activation time parameter. For more information, see Types of Operators in Variant Blocks for Different Activation Times

  • Comparison values — Values to compare against variant control variables. These can be any valid MATLAB data type, including numeric, logical, enumeration, or other appropriate types.

Types of Variant Control Variables (Operands) in Variant Blocks

In variant blocks, use Simulink.VariantControl objects for variant control variables. A Simulink.VariantControl object associates the value of a variant control variable with Variant activation time, which helps prevent incorrect variant selection in applications that require frequent variant switching. The Simulink.VariantControl objects also centralize the variant activation logic. When you update a Simulink.VariantControl variable, variant blocks and variant parameters that share this control are synchronized, avoiding mismatches across different portions of the model.

Alternatively, you can use other types as variant control variables, such as scalar variables for quick prototyping and simple models, or Simulink.Parameter objects to specify additional properties and support code generation.

You can define variant control variables in different storage locations based on your requirements. If you define a variable with the same name in the base workspace, a mask workspace, and the model workspace, Simulink evaluates the variable first in the mask workspace, then in the model workspace, and finally in the base workspace. Simulink gives priority to the definition in the closest context, so the most relevant value is used to evaluate variant condition expressions. For details on the capabilities and advantages of each storage location, see Determine Where to Store Variables and Objects for Simulink Models.

Note

  • Variant control variables defined in a mask workspace are local to that mask and cannot activate a variant block outside the mask. To extend their scope beyond the mask, define the variant control variable as a mask parameter.

  • All variant control variables in a variant block must originate from the same workspace.

  • Use a Simulink.SimulationInput object to temporarily set values of variant control variables for each simulation run. The object is useful with startup variants in applications like testing, iterative simulation, and rapid prototyping, because you do not need to change workspace variables.

  • For the Initialize Function, Reset Function, Reinitialize Function, Terminate Function, and Simulink Function blocks, define variant control variables in the base workspace or within a data dictionary when the Generate preprocessor conditionals parameter is selected.

This table summarizes the types of variant control variables supported in variant blocks. It specifies where you can define each type of variant control variable, the supported variant activation times for each type. For examples on how to use different types of variant control variables, see Use Variant Control Variables in Variant Blocks.

Type of variant control variableWorkspace supportedupdate diagramupdate diagram analyze all choicescode compilestartupruntime

Simulink.VariantControl — Associate the variant control variable with the variant activation time to centralize and synchronize variant activation logic across variant blocks and parameters to prevent incorrect variant selections during frequent variant switching.

See Use Simulink.VariantControl Variables for Coherent Switching of Choices in Variant Blocks.

base workspace

data dictionary

✓✓✓✓✓

model workspace

mask workspace

✓✓ ✓✓

Simulink.Parameter — Set the Simulink.VariantControl object to an object of a user-defined data class derived from Simulink.Parameter. You can extend the standard parameter behavior by incorporating additional properties, methods, or validation within the parameter by using the custom storage classes defined in your package. The package containing your custom data class must be available on the MATLAB search path.

See Use Custom Data Class Objects as Values of Simulink.VariantControl Objects.

base workspace

data dictionary

✓✓✓✓✓

model workspace

✓✓ ✓✓

Simulink.Parameter — Set the Simulink.VariantControl object to a Simulink.Parameter object (or an object inheriting from it) with its value defined as a mathematical expression using the slexpr function. This approach allows you to specify the value as a relationship between known physical constants instead of using an arbitrary literal number. Additionally, it enables you to explicitly model algebraic dependencies between parameter data, so when you modify the values of independent parameters, the dependent parameters update automatically.

See Use Mathematical Expressions as Values of Simulink.VariantControl Objects and Simulink.VariantVariable Choices.

base workspace

data dictionary

✓✓✓✓✓

model workspace

✓✓ ✓✓

Simulink.Parameter — Control the scope, placement, accessibility, and visibility of the variable in the generated code by defining its storage class.

See Simulink.Parameter Type of Variant Control Variables for Code Generation in Variant Blocks.

base workspace

data dictionary

✓✓✓✓✓

model workspace

✓✓ ✓✓

Scalar variable — Rapid prototyping and simulation for quick variant switching.

See Scalar Variant Control Variables for Rapid Prototyping in Variant Blocks.

base workspace

data dictionary

✓✓✓✓✓

model workspace

mask workspace

✓✓ ✓✓

Tip

How to Choose the Right Variant Control Variable and Comparison Value in Variant Blocks

In variant blocks, use Simulink.VariantControl objects for variant control variables. A Simulink.VariantControl object associates the value of a variant control variable with Variant activation time, which helps prevent incorrect variant selection in applications that require frequent variant switching. The Simulink.VariantControl objects also centralize the variant activation logic. When you update a Simulink.VariantControl variable, variant blocks and variant parameters that share this control are synchronized, avoiding mismatches across different portions of the model.

Alternatively, you can use other types as variant control variables, such as scalar variables for quick prototyping and simple models, or Simulink.Parameter objects to specify additional properties and support code generation.

Use this flowchart to determine the appropriate type of variant control variable and the value to assign based on your requirements. After selecting the type of variant control variable, choose the appropriate data type for its value.

If you selected Simulink.VariantControl as the type for your variant control variable, use this flowchart to determine the appropriate data type for its value.

If you selected Simulink.Parameter as the type for your variant control variable, refer to the flow chart below to determine the appropriate data type for its value.

Types of Operators in Variant Blocks for Different Activation Times

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

In variant blocks, the operators that you can use to form a variant condition expression depends on the Variant activation time.

When you specify the Variant activation time as:

  • update diagram — Any condition expression that evaluates to true or false.

  • update diagram analyze all choices or code compile — The supported operators are:

    • Parentheses for grouping

    • Arithmetic Operators, Relational Operators, Logical Operators, and Bit-Wise Operations, as listed in this table.

      This table lists the MATLAB operators and their representation in the generated code. In these examples, A and B are expressions that evaluate to an integer, and x is a constant integer literal.

      MATLAB Expressions That Support Generation of Preprocessor ConditionalsEquivalent Expression in C Preprocessor Conditional of Generated Code
      Arithmetic

      • A + B

      • +A

      • A + B

      • A

      • A - B

      • -A

      • A - B

      • -A

      A * BA * B
      idivide(A,B)

      A / B

      If the value of the second operand (B) is 0, the behavior is undefined.

      rem(A,B)

      A % B

      If the value of the second operand (B) is 0, the behavior is undefined.

      Relational

      A == B

      		A == B

      A ~= B

      		A != B

      A < B

      		A < B

      A > B

      		A > B

      A <= B

      		A <= B

      A >= B

      		A >= B
      Logical
      ~A!A, where A is not an integer
      A && BA && B
      A || BA || B
      Bitwise (A and B cannot both be constant integer literals)

      bitand(A,B)

      		A & B

      bitor(A,B)

      		A | B

      bitxor(A,B)

      		A ^ B

      bitcmp(A)

      		~A

      bitshift(A,x)

      		A << x

      bitshift(A,-x)

      		A >> x

  • startup — The supported operators are:

    • Parentheses for grouping

    • Relational Operators and Logical Operators, as listed in this table.

      This table lists the MATLAB operators and their representation in the generated code. In these examples, A and B are expressions that evaluate to an integer.

      Supported Operators in Variant Condition ExpressionEquivalent Expression in Regular if of Generated Code
      Relational

      A == B

      		A == B

      A ~= B

      		A != B
      Logical
      ~A!A, where A is not an integer
      A && BA && B
      A || BA || B

Note

In variant blocks with startup activation time:

  • For the variant control variables with any activation time, the variant control variables that originate from the mask or the model workspace cannot be used in the MATLAB in-built functions such as idivide, bitand, and so on to form expressions.

  • AUTOSAR post-build variants support only == and && operators. For more information, see Configure Postbuild Variant Conditions for AUTOSAR Software Components (AUTOSAR Blockset).

Evaluate Variant Condition Expressions at Different Variant Activation Times

In expression mode, you can specify if Simulink must evaluate condition expressions during model compile, simulation-loop, code compile, or model start up stage of simulation and code generation workflow using variant activation times. For information on stages of simulation and code generation and supported variant activation times in expression mode, 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 limit variant condition propagation in a bounded region using the Variant Start and Variant End blocks. For more information on bounded region, see Variant Start.

You can use the Variant 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 Legend displays the condition that corresponds to each annotation.

For more information, see Propagate Variant Conditions to Define Variant Regions with Variant Blocks.

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.

Note

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 or generate code from a model, Simulink determines the active choice in the model compilation stage and generates code only for the active choice. See Activate Variant During Different Stages of Simulation and Code Generation Workflow.

Use label Mode in Variant Blocks

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

 Variant control mode: label

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 using the initialization code. Using the mask initialization code, you can specify the active choice from variant block or any subsystem in the hierarchy. 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.

  • Use 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 Without Using Control Variables in Variant Blocks

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

Note

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.

Use sim codegen switching Mode in Variant Blocks

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

When you simulate a model in normal, accelerator, or rapid Accelerator mode, 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

Compare Different Types of Variant Control Modes in Variant Blocks

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:

  • Control active choices without creating any workspace variables.

  • Generate code only for active choice in the model.

sim codegen switching — When you simulate a model in normal, accelerator, or rapid Accelerator mode, 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 in Variant Blocks

This table explains the variant activation time supported for different variant control modes in variant blocks. For information on variant activation times, see Activate Variant During Different Stages of Simulation and Code Generation Workflow.

Variant activation time
Variant blocksVariant control modeupdate diagramupdate diagram analyze all choicescode compilestartupruntime
Variant Subsystemexpression✓✓✓✓✓
label✓xxxx
sim codegen switching✓✓xxx
Variant Model, Variant Source, Variant SinkVariant StartVariant Endexpression✓✓✓✓not supported
label✓xxxnot supported
sim codegen switching✓✓xxnot supported
Variant Connector (Simscape), Manual Variant Source, Manual Variant Sinkexpression✓xxxnot supported
labelnot supportednot supported
sim codegen switchingnot supportednot supported
Simulink Function, Initialize Function, Reset Function, and Terminate Functionexpression✓x✓xnot supported
labelnot supportednot supported
sim codegen switchingnot supportednot supported

See Also

Topics