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 conditional expression called 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.

A variant control is a Boolean expression that activates a specific variant choice when it evaluates to true.

Note

You can specify variant controls in the MATLAB^® global workspace, mask workspace, or a data dictionary.

You can specify variant controls as Simulink.Variant objects, MATLAB expressions (including structures) or as expressions that contain one or more of these operands and operators.

Variant control mode

Variant control mode parameter available in the block parameters dialog box allows you to select Expression or Label or sim codegen switching mode for modeling Variant blocks.

Expression: Specifies the active Variant based on the evaluation of the Variant conditions.
Variant control mode: Expression
Label: Specifies the name based Variant controls (Label mode active choice). In Label mode, Variant control need not be created in the global workspace. Alternatively, you can select the Label mode active choice from the command line. For example, set_param(block,'LabelModeActiveChoice', 'Choice_1').
Variant control mode: Label
sim codegen switching: enables automatic variant switching for simulation and code-generation workflows in variant blocks. This feature is convenient to switch between simulation and code-generation modes.
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) simulation, Processor-In-Loop (PIL) simulation or generate code or use external mode, Simulink automatically chooses the codegen branch.
Note
If a variant block has Variant control mode set to label or expression, then using sim or codgen for its choice condition is not supported.
Variant control mode: sim codegen switching
Note
In the Variant activation time drop-down list, you can choose update diagram or update diagram analyze all choices. For data signals, update diagram analyze all choices ensures that the signal attributes (data types, dimensions, etc.) between both choices are consistent.
Here is a sample screen showing a variant block switched to sim choice.

Operands

Variable names that resolve to MATLAB variables or Simulink.Parameter objects with integer or enumerated data type and scalar literal values
Variable names that resolve to Simulink.Variant objects
Scalar literal values that represent integer or enumerated values

Operators

Parentheses for grouping
Arithmetic, relational, logical, or bitwise operators

For more information, see Operators and Operands in Variant Condition Expressions.

When you compile the model, Simulink determines that a variant choice is active if its variant control evaluates to true. The evaluation of active variant happens in the early stages of compilation and the active variant cannot be changed once model is compiled.

Known Limitations

Simulink variant objects within structures are not allowed.
Simulink parameters within structures are not allowed.

Approaches for Specifying Variant Controls

You can use many approaches for switching between variant choices—from options to use while prototyping to options required for generating code from your model.

Specification	Purpose	Example
Scalar variable	Rapid prototyping	`A == 1`
`Simulink.Variant` object	Reuse variant conditions	`LinearController = Simulink.Variant('FUEL==2 && EMIS==1');`
`Simulink.Parameter` object or MATLAB variables	Generate preprocessor conditionals for code generation	`mode == 1`, where `mode` can be `Simulink.Parameter` object or MATLAB variables
Enumerated type	Improved code readability because condition values are represented as meaningful names instead of integers	`LEVEL == Level.Advanced`

You can find control variables using the function Simulink.VariantManager.findVariantControlVars.

Scalar Variables for Rapid Prototyping

Scalar MATLAB 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.

Consider a model that contains two variant choices, each represented by a Variant Subsystem block.

You can specify variant controls in their simplest form as scalar variables in the block parameters dialog box of the Variant Subsystem block.

The Condition field for both the Linear Controller and Nonlinear Controller are N/A, because the variant control itself is the condition.

You can activate one of the variant choices by defining a scalar variable V and setting its value to 1 at the MATLAB Command Window.

V = 1;

This condition activates the Linear Controller variant choice. Variant controls are ignored when % symbol is used. Similarly, if variant control is empty, the choice is ignored.

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

`Simulink.Variant` Objects for Variant Condition Reuse

After identifying the variant choices that your model requires, you can construct complex variant conditions to control the activation of your variant choices. Define 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.

Consider an example where variant controls are already defined in the global workspace.

V=1;
V=2;

You can convert these controls into condition expressions encapsulated as Simulink.Variant objects.

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

You can then specify these Simulink.Variant objects as the variant controls in the block parameters dialog box of the Variant Subsystem block.

The Condition field now reflects the encapsulated variant condition. Using this approach, you can develop complex variant condition expressions that are reusable.

`Simulink.Parameter` Objects or MATLAB variables for Code Generation

If you intend to generate code for a model containing variant choices, 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.

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. See Convert Variant Control Variables into Simulink.Parameter Objects.

Enumerated Types for Improving Code Readability

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

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

classdef sldemo_mrv_CONTROLLER_TYPE < Simulink.IntEnumType
        enumeration
        NONLINEAR (1)
        SECOND_ORDER (2)
        end
end

Define Simulink.Variant objects for these classes in the global workspace.

VE_NONLINEAR_CONTROLLER = Simulink.Variant...
('E_CTRL==sldemo_mrv_CONTROLLER_TYPE.NONLINEAR')
VE_SECOND_ORDER_CONTROLLER =Simulink.Variant...
('E_CTRL==sldemo_mrv_CONTROLLER_TYPE.SECOND_ORDER')
VE_PROTOTYPE =Simulink.Variant...
('E_CURRENT_BUILD==sldemo_mrv_BUILD_TYPE.PROTOTYPE')
VE_PRODUCTION =Simulink.Variant...
('E_CURRENT_BUILD==sldemo_mrv_BUILD_TYPE.PRODUCTION')

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

Viewing Variant Conditions

The Variant Condition Legend helps you visualize the variant conditions associated with a model. To view the Variant Condition Legend, on the Debug tab, select Information Overlays > Variant Legend.

Note

If Variant Legend is not available, on the Debug tab, select Information Overlays > Variant Conditions.

By default, the Variant Condition Legend displays the variant condition annotation, the variant condition during simulation, and the source of the variant condition variables. To view the variant condition in the generated code, select the Show generated code conditions option in the Variant Condition Legend window.

In the Variant Condition Legend, the variant conditions on the blocks are annotated as v:c, where v is the variant semantic indicator and c represents the variant condition index. You can click through the hyperlinked variant annotations to observe which parts of the model the condition corresponds to.

When you hover over a block that has a variant condition, the tooltip displays the variant annotation and the related variant condition for the block. To view the variant condition annotation tooltip, the Variant Condition option must be selected.

In the legend, the source of the variant condition variables are also displayed. The variables can originate from a mask, model, or a base workspace. The variables originating from different mask workspaces can have the same name and have different values. To observe the source of the variables, click the hyperlinked workspaces.

To view the Variant Condition Legend programmatically, use the Simulink.VariantManager.VariantLegend function in the MATLAB command window.

Operators and Operands in Variant Condition Expressions

Simulink evaluates condition expressions within variant controls to determine the active variant choice. You can include the following operands in a condition expression:

Scalar variables
Simulink.Parameter objects that are not structures and that have data types other than Simulink.Bus objects
Enumerated types
Parentheses for grouping

Variant condition expressions can contain MATLAB operators, provided the expression evaluates to a boolean value. 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 Conditionals	Equivalent Expression in C Preprocessor Conditional
Arithmetic
`A + B` `+A`	`A + B` `A`
`A - B` `-A`	`A - B` `-A`
`A * B`	`A * 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 && B`	`A && B`
`A \|\| B`	`A \|\| 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`

Net Variant Condition

The net variant condition is the total of the local condition and its ancestral condition.

Consider this model slex_netvariant with two Single-input Single-Output (SISO) Variant Source blocks, Variant Source and Variant Source1 with variant conditions as V==1 and W==1, respectively.

When you simulate this model, the Variant Source1 block and other blocks within the Subsystem block will have a local condition W==1 propagated from the Variant Source1 block. The ancestral condition V==1 is propagated from the Variant Source block onto the Subsystem block. Therefore, the net variant condition on the Variant Source1 block and other blocks within the Subsystem block will be V==1 && W==1.

Documentation