This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

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 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 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', 'Variant1').

    Variant control mode: Label

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.

SpecificationPurposeExample
Scalar variableRapid prototypingA == 1
Simulink.Variant objectReuse variant conditionsLinearController = Simulink.Variant('FUEL==2 && EMIS==1');
Simulink.Parameter object or MATLAB variablesGenerate preprocessor conditionals for code generationmode == 1, where mode can be Simulink.Parameter object or MATLAB variables
Enumerated typeImproved code readability because condition values are represented as meaningful names instead of integersLEVEL == 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 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 custom 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.

  1. 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
    
    classdef sldemo_mrv_BUILD_TYPE < Simulink.IntEnumType
            enumeration
            PROTOTYPE (1)
            PRODUCTION (2)
            end
    end
    
  2. 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, click Display > Blocks > Variant Condition Legend.

Note

The Variant Condition Legend is available only when Display > Blocks > Variant Condition is active.

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

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.

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 ConditionalsEquivalent Expression in C Preprocessor Conditional
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

Related Examples

More About