Simulink.VariantVariable class

Package: Simulink

Create a variant parameter object

Description

The Simulink.VariantVariable class creates a variant parameter object. You can specify multiple values for each object. You can also specify properties such as dimension, data type, and so on. Each value of the object is associated with a variant condition expression. Set the parameter values and properties in the object, then reference the object from the block.

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.

Creation

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

P= Simulink.VariantVariable(Name,Value)creates a variant parameter object as specified by one or more Name,Value pair 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.

Input Arguments

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: 'Specification', 'Pspec', 'Choices', {'V==1', 4.5, 'V==2', 9.5}

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

Example: 'Specification', 'Pspec'

Choices — Variant conditions and values

cell array

Variant conditions and values, specified as a struct. 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.

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

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

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

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

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

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

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.

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.

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