Main Content

Simulink.VariantControl class

Package: Simulink

Create a variant control variable object

Description

The Simulink.VariantControl class creates a variant control variable object to associate the value of a variant control variable with a variant activation time. Use the Simulink.VariantControl object to determine the active value of variant parameter during simulation.

Creation

variantControlVariable = Simulink.VariantControl creates a variant control variable object with no value and 'ActivationTime' set to 'update diagram'.

variantControlVariable = Simulink.VariantControl(Name,Value) creates a variant control variable object as specified by Name,Value pair arguments. Using this syntax, you create an object and associate its value with a variant activation time.

Input Arguments

expand all

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'Value', 1, 'ActivationTime', 'update diagram'

Value of variant control variable object, specified as scalar variables, enumerated types, or Simulink.Parameter object.

Example: 'Value', 1

Simulink® can set active value of the variant parameters at different stages of the simulation and code generation workflow. Based on the stage you specify using this property, Simulink determines if the generated code must contain only the active values or both active and inactive values of variant parameters. The property also determines whether to analyze all the values of the variant parameters for incompatibilities in signal attributes. For more information on variant activation time, see Activate Variant During Different Stages of Simulation and Code Generation Workflow.

When you specify the variant activation time as:

  • 'update diagram' –– Simulink does not analyze the values of variant parameters for incompatibilities in signal attributes. It generates code only for the active values of variant parameters.

  • 'update diagram analyze all choices' –– Simulink analyzes both active and inactive values of variant parameters for incompatibilities in signal attributes, however it generates code only for the active values of variant parameters.

  • 'code compile' –– Simulink analyzes both active and inactive values of variant parameters for incompatibilities in signal attributes and it also generates code for both active and inactive values of the variant parameters. The values are enclosed in C preprocessor conditional statements #if and #endif that are conditionally compiled when you compile the generated code.

  • 'startup' –– Simulink analyzes both active and inactive values of variant parameters for incompatibilities in signal attributes and it also generates code for both active and inactive values of the variant parameters. The values are enclosed in regular if conditions inside the model_initialize function of the generated code that are conditionally evaluated when you run the executable that is built from the code.

Example: 'ActivationTime', 'code compile'

Methods

expand all

Examples

collapse all

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

You can define numeric control values in locations listed in Storage Locations for Variant Control Variables (Operands) in Variant Blocks.

Open the slexVariantParameters model.

open_system('slexVariantParameters')

In the MATLAB Editor, specify variant choices in their simplest form as numeric values in Simulink.VariantVariable objects K1 and K2.

K1 = Simulink.VariantVariable('Choices',{'V==1', 3.5, 'V==2', 8.5})
K1 = 
VariantVariable with 2 choices:

Condition	Value
_________	_____
V == 1   	3.5000
V == 2   	8.5000

Specification: ''

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

K2 = Simulink.VariantVariable('Choices',{'V==1', 4.5, 'V==2', 9.5})
K2 = 
VariantVariable with 2 choices:

Condition	Value
_________	_____
V == 1   	4.5000
V == 2   	9.5000

Specification: ''

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

Once you successfully create the Simulink.VariantVariable objects, you can modify them by using the methods described in Public Methods or from the VariantVariable dialog box.

Activate one of the variant values by defining a control variable, V, and setting its value to 1 in a Simulink.VariantControl object.

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

             Value: 1
    ActivationTime: 'update diagram'

When you simulate the model, the condition V == 1 evaluates to true. K1 is assigned a value of 3.5 and K2 is assigned a value of 8.5.

sim ('slexVariantParameters')

If you change the value of V to 2, Simulink® sets the value of K1 and K2 to 4.5 and 9.5 during simulation. You can change the value of V using this command or from Simulink.VariantControl dialog box.

V.Value = 2;
sim ('slexVariantParameters')

Use enumerated types to give meaningful names to integers used as variant control values.For more information on enumerated type data, see Use Enumerated Data in Simulink Models.

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

Open the slexVariantParameters model.

open_system('slexVariantParameters')

Specify the variant condition expressions V == EngType.Small and V == EngType.Big in Simulink.VariantVariable objects K1 and K2.

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

     Condition     	Value
__________________	_____
V == EngType.Big  	8.5000
V == EngType.Small	3.5000

Specification: ''

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

K2 = Simulink.VariantVariable('Choices', {'V == EngType.Small',4.5,'V == EngType.Big',9.5})
K2 = 
VariantVariable with 2 choices:

     Condition     	Value
__________________	_____
V == EngType.Big  	9.5000
V == EngType.Small	4.5000

Specification: ''

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

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.In this example, the enumeration class is defined in the base workspace. You can choose to define the class in other storage locations as listed in Storage Locations for Variant Control Variables (Operands) in Variant Blocks.

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

Once you successfully create the Simulink.VariantVariable objects, you can modify them by using the methods described in Public Methods or from the VariantVariable dialog box.

Activate one of the variant values by defining the control variable V and setting its value to EngType.Small in Simulink.VariantControl object V.

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

             Value: Small
    ActivationTime: 'code compile'

When you simulate the model, the condition V == 1 evaluates to true. K1 is assigned a value of 3.5, and K2 is assigned a value of 8.5.

sim('slexVariantParameters')

If you change the value of V to 2, Simulink® sets the value of K1 and K2 to 4.5 and 9.5 during simulation. You can change the value of V using this command or from Simulink.VariantControl dialog box.

V.Value = 2
V = 
  VariantControl with properties:

             Value: 2
    ActivationTime: 'code compile'

sim ('slexVariantParameters')

The code that you generate using enumerated types contains the names of the values rather than integers.

% slexVariantParameters_private.h
% #if V == EngType_Big || V == EngType_Small
%     /* Variable: K1 Referenced by: '<Root>/Gain' */
%     #if V == EngType_Big
%       #define rtCP_Gain_K1                   (8.5)
%     #elif V == EngType_Small
%       #define rtCP_Gain_K1                   (3.5)
%     #endif
% #endif
% 
% #if V == EngType_Big || V == EngType_Small
%    /* Variable: K2 Referenced by: '<Root>/Gain1' */
%     #if V == EngType_Big
%       #define rtCP_Gain1_K2                  (9.5)
%     #elif V == EngType_Small
%       #define rtCP_Gain1_K2                  (4.5)
%     #endif
% #endif
% #endif                         /* RTW_HEADER_slexVariantParameters_private_h_ */

Note that for variant parameters with startup activation time, only enumerations that are defined using these techniques are supported:

  • Using the function Simulink.defineIntEnumType

  • By subclassing built-in integer data types int8, int16, int32, uint8, or uint16, or by subclassing Simulink.IntEnumType

These enumerations are also supported when permanently stored in a Simulink® data dictionary. See Enumerations in Data Dictionary.

If you intend to generate code for a model containing variant parameters, specify variant control variables as Simulink.Parameter objects. Simulink.Parameter objects allow you to specify other attributes, such as data type and storage class, and control the appearance and placement of variant control variables in generated code.

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

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

Open the slexVariantParameters model.

open_system('slexVariantParameters')

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

VSS_MODE = Simulink.Parameter;
VSS_MODE.Value = 1;
VSS_MODE.DataType = 'int32';
VSS_MODE.CoderInfo.StorageClass = 'Custom';
VSS_MODE.CoderInfo.CustomStorageClass = 'Define';
VSS_MODE.CoderInfo.CustomAttributes.HeaderFile ='demo_macros.h'; 

Variant control variables defined as Simulink.Parameter objects can have any of the storage classes listed in Storage Classes for Different Variant Activation Times (Embedded 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.

Specify the object as a variant control in Simulink.VariantVariable objects K1 and K2.

K1 = Simulink.VariantVariable('Choices',{'V == 1', 3.5, 'V == 2', 8.5})
K1 = 
VariantVariable with 2 choices:

Condition	Value
_________	_____
V == 1   	3.5000
V == 2   	8.5000

Specification: ''

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

K2 = Simulink.VariantVariable('Choices',{'V == 1', 4.5, 'V == 2', 9.5})
K2 = 
VariantVariable with 2 choices:

Condition	Value
_________	_____
V == 1   	4.5000
V == 2   	9.5000

Specification: ''

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

Once you successfully create the Simulink.VariantVariable objects, you can modify them by using the methods described in Public Methods or from the VariantVariable dialog box.

Activate one of the variant values by defining a control variable V and setting its value to VSS_MODE in a Simulink.VariantControl object.

V = Simulink.VariantControl('Value',VSS_MODE,'ActivationTime','code compile')
V = 
  VariantControl with properties:

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

When you simulate the model, the condition V == 1 evaluates to true. K1 is assigned a value of 3.5, and K2 is assigned a value of 8.5.

sim ('slexVariantParameters')

If you change the value of VSS_MODE to 2, Simulink® sets the value of K1 and K2 to 4.5 and 9.5 during simulation. You can change the value of V using this command or from Simulink.VariantControl dialog box.

VSS_MODE.Value = 2;
V.Value = VSS_MODE;
sim ('slexVariantParameters')

Generate code from the model. For information on how to generate code, see Generate Code Using Embedded Coder (Embedded Coder)

The generated code contains both Linear and Nonlinear choices in preprocessor conditionals #if and #elif because of the code compile activation time. The variant control variable V is defined using a macro — #define directive — in the header file demo_macros.h. You can control the appearance and placement of V in the generated code and prevent optimizations from eliminating storage for V using the storage class property. For more information, see Storage Classes for Different Variant Activation Times (Embedded Coder).

% demo_macros.h
% /* Exported data define */
% 
% /* Definition for custom storage class: Define */
% #define V       2          /* Referenced by:
%                            * '<Root>/Gain'
%                            * '<Root>/Gain1'
%                            */
% #endif                    /* RTW_HEADER_demo_macros_h_ */
% 
% /*

Extended Capabilities

Version History

Introduced in R2021a