Simulink.VariantVariable class

Package: Simulink

Create a variant parameter object

Since R2021a

Description

The Simulink.VariantVariable class creates a variant parameter object. Variant parameter objects enable you to vary the values of block parameters in a Simulink^® model conditionally.

You can specify multiple values for a variant parameter object. You can also specify properties such as dimension, data type, and so on. Each value of the variant parameter object is associated with a variant condition expression. After creating the object, you can use it to set the value of block parameters in a model, such as the Gain parameter of a Gain block. During simulation, the value associated with the variant condition that evaluates to true becomes the active value of that parameter. The values associated with the conditions that evaluate to false become inactive.

Before you create a new Simulink.VariantVariable object, create a Simulink.VariantControl object representing the variant control variable to be used in the Simulink.VariantVariable object.

Note

You can create the variant parameter object only in the base workspace or in a data dictionary.

To edit a variant parameter object, you can double-click the object from the workspace or data dictionary to open the Simulink.VariantVariable dialog box.

Variant Conditions Legend does not display the variant conditions for variant parameters. Use the Variant Parameters tab in the Variant Manager window to view the variant parameters present in the base workspace or data dictionaries associated with the model and to edit the variant condition and value of the choices.

Creation

P= Simulink.VariantVariable creates an empty variant parameter object.

P= Simulink.VariantVariable(Name,Value) creates a variant parameter object and sets Properties using one or more Name,Value arguments. Using this syntax, you can specify multiple values for the object and associate each value with a variant condition expression. You can also specify other properties of the object such as data types, storage class, dimensions, and so on.

Properties

Specification — Properties of variant parameter object

Simulink.Parameter object name

Properties of variant parameter object such as data type, dimensions, storage class, and so on, specified as the Simulink.Parameter object. The default storage class of a Simulink.Parameter object is Auto. If you specify the storage class as Auto, the value of the object is inlined to the literal value in the generated code. If you specify the storage class of the object anything other than Auto, the object is represented as tunable parameters using symbolic names in the generated code. For more information, see Options to Represent Variant Parameters in Generated Code (Embedded Coder).

Note

Specifying storage class using the Specification property is not supported if the Simulink.VariantVariable object is part of a variant parameter bank (Simulink.VariantBank).

Example: 'Specification', 'Pspec'

Attributes:

GetAccess	public
SetAccess	public

Choices — Variant conditions and values

cell array

Variant conditions and values, specified as a cell array. During simulation, when a variant condition evaluates to true, its associated value becomes active. When a variant condition evaluates to false, its associated value becomes inactive. No two values of the same variant parameter must be associated with the same variant condition.

You can specify the variant condition as boolean MATLAB^® expressions that contain one or more operands and operators. See Types of Variant Control Variables (Operands) in Variant Parameters and Types of Operators in Variant Parameters.

You can specify values of numeric, enumerated, or Simulink.Parameter type. See, Numeric Variant Control Values for Rapid Prototyping of Variant Parameters, Improve Code Readability of Variant Parameters Using Enumerated Types, and Reuse Variant Parameter Values from Handwritten Code Using Simulink.Parameter Variables.

You can specify one of the choice values as a default value for the variant parameter by setting its variant condition as (default). Simulink uses the default value for the variant parameter when none of the other variant conditions evaluate to true.

Example: 'Choices', {'V == 1', 4.5, 'V==2', 9.5}

Example: 'Choices', {'V == 1', 3, '(default)', 6}

Attributes:

GetAccess	private
SetAccess	private

Bank — Name of variant parameter bank

'' (default) | string | character vector

Name of variant parameter bank (Simulink.VariantBank) object, specified as a string or character vector.

With Embedded Coder^®, you can group variant parameters in the generated code by adding them to the same variant parameter bank. The variant parameters must have startup activation time and must have the same set of variant conditions. Use the Simulink.VariantBank class to create a variant parameter bank object and set the Bank property of the Simulink.VariantVariable object to the name of the variant parameter bank. For more information, see Simulink.VariantBank.

Example: 'Bank', 'EngineParams'

Attributes:

GetAccess	public
SetAccess	public

Data Types: string | char

Methods

Public Methods

addChoice	Add choices to variant parameter object
getChoice	Return choices of variant parameter object
setChoice	Modify existing choices of variant parameter object
removeChoice	Remove choices from variant parameter object

Specialized Operators and Functions

These methods specialize standard MATLAB operators and functions for objects in this class.

bitcmp	Performs bit-wise complement on input.
eq	Compares if the inputs are equal.
gt	Compares if the first input is greater than the second input.
mrdivide	Divides the first input by the second input.
or	Performs a logical OR on inputs.
uminus	Negates the input.
bitor	Performs bit-wise OR on inputs.
ge	Compares if the first input is greater than or equal to the second input.
le	Compares if the first input is less than or equal to the second input.
mtimes	Multiplies the inputs.
plus	Adds the inputs.
uplus	Returns the value of the input.
and	Performs logical AND on inputs.
bitshift	Shift bits by specified number of places.
lt	Compares if the first input is less than the second input.
ne	Compares if the inputs are not equal.
bitand	Performs bit-wise AND on inputs.
bitxor	Performs bit-wise XOR on inputs.
minus	Subtracts the second input from the first input.
not	Returns logical NOT of input.

Examples

Numeric Variant Control Values for Rapid Prototyping of Variant Parameters

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

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: ''

Bank: ''

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: ''

Bank: ''

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')

Simulink.Parameter Type of Variant Control Variables for Code Generation of Variant Parameters

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

• 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: ''

Bank: ''

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: ''

Bank: ''

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_ */
% 
% /*

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.

• You can define a variant control variable of type Simulink.Variant only in the base workspace or in a data dictionary. Defining Simulink.Variant 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 Parameters.

• Simulink.Variant within structures are not supported.

Open the slexVariantParameters model.

open_system('slexVariantParameters')

In the MATLAB® Editor, encapsulate variant control expressions as Simulink.Variant objects.

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

Specify the Simulink.Variant objects as the variant controls in a Simulink.VariantVariable objects K1 and K2.

K1 = Simulink.VariantVariable('Choices',{'LinearController',3.5,'NonLinearController',8.5})

K1 = 
VariantVariable with 2 choices:

     Condition     	Value
___________________	_____
LinearController   	3.5000
NonLinearController	8.5000

Specification: ''

Bank: ''

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

K2 = Simulink.VariantVariable('Choices',{'LinearController',4.5,'NonLinearController',9.5})

K2 = 
VariantVariable with 2 choices:

     Condition     	Value
___________________	_____
LinearController   	4.5000
NonLinearController	9.5000

Specification: ''

Bank: ''

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 Simulink.VariantControl object V and setting its value to 1.

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')

Using this approach, you can develop complex variant condition expressions that are reusable.

Limitations

• Variant parameters that are part of a variant parameter bank do not support AUTOSAR code generation.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

• For variant parameters associated with the startup activation time, you can generate code for both active and inactive choices by installing Simulink Coder™ or Embedded Coder.

• For variant parameters associated with the code compile activation time:

  • You must install Simulink Coder to generate code for only active values of variant parameters. Generating code using Simulink Coder is supported only if values of a variant parameter have same dimension.

  • You must install Embedded Coder to generate code for both active and inactive values of variant parameters. Generating code using Embedded Coder is supported for variant parameters values having same and different dimensions.

• When you generate code using Embedded Coder, you can group variant parameters that have the same set of variant conditions and use startup activation time into a structure array in the generated code. Use the Simulink.VariantBank class to group variant parameters into a variant parameter bank and use the Simulink.VariantBankCoderInfo class to specify code generation properties for the variant parameter bank.

For more information on code generation with variant parameters, see Options to Represent Variant Parameters in Generated Code (Embedded Coder).

Version History

Introduced in R2021a

R2023a: New Bank property

You can use the Bank property to add a Simulink.VariantVariable object to a variant parameter bank (Simulink.VariantBank).