Main Content

Variant Controls in Variant Parameters

The values of a variant parameter in a Simulink® model are activated or deactivated based on the variant control expression that evaluates to true.

Each value of a variant parameter in a Simulink model is associated with a conditional expression called variant control expression. Variant controls determine which value of the variant parameter is active. By changing the value of a variant control, you can switch the active value of a variant parameter.

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

Note

You can specify variant controls only in the MATLAB® base workspace or in a data dictionary.

You can specify variant controls as boolean MATLAB expressions or Simulink.Variant object specifying expressions. The expressions can contain one or more of these Operands and Operators.

Operands

  • Variables that represent Simulink.VariantControl objects

  • Scalar literal values that are integer or enumerated values

Operators

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.

MATLAB Expressions That Support Generation of Preprocessor ConditionalsEquivalent Expression in C Preprocessor Conditional
Relational

A == B

A == B

A ~= B

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

Approaches for Specifying Variant Controls

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

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

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.