Simulink.VariantVariable Class

Namespace: Simulink

Create variant parameter object

Since R2021a

Description

Use the Simulink.VariantVariable class to create a variant parameter object. Variant parameter objects enable you to vary the values of block parameters in a Simulink^® model conditionally. For an overview of variant parameters, see Use Variant Parameters to Reuse Block Parameters with Different Values.

You can specify multiple values for a variant parameter object and also set properties such as data type and dimensions applicable to all the choice values. Each value of the variant parameter object is associated with a variant condition expression. After creating the object, 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 for 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. Use these variant control variables to specify the variant condition expression associated with each choice value of a variant parameter, for example, 'V == 1' where V is a Simulink.VariantControl object. The Simulink.VariantControl object allows you to specify an ActivationTime for the variant parameter and a Value that is used to evaluate the variant conditions and determine the active choice of the variant parameter. For examples on usage of each type of variant control value, see Use Variant Control Variables in Variant Parameters.

Note

You create a variant parameter object in the base workspace or in a data dictionary. You can add Simulink.VariantVariable and Simulink.VariantControl objects to the base workspace or the Design Data section of a data dictionary either programmatically or from the Add menu in the Model Explorer.

To edit a variant parameter object, 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 and manage the variant parameters present in the base workspace or data dictionaries associated with the model. See Variant Manager for Simulink.

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. Use this syntax to specify multiple values for the object and to associate each value with a variant condition expression. You can also specify other properties of the object such as data type, storage class, and dimension.

Properties

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 can be associated with the same variant condition.

You can specify the variant conditions as boolean MATLAB^® expressions. For information on the supported operators and operands, see Variant Control Mode in Variant Parameters.

The choice value can be a numeric value or the name of a Simulink.Parameter object.

Arithmetic and logical operations on a variant parameter object applies the operation on the active choice value. For example, p + 2 adds 2 to the active choice value of p.

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

Example: P = Simulink.VariantVariable('Choices',{'V == 1',4.5,'V == 2',9.5})

Example: P = Simulink.VariantVariable('Choices',{'V == 1',3,'(default)',6})

Attributes:

GetAccess	private
SetAccess	private

Specification — Properties of variant parameter object

Simulink.Parameter object name

Properties of variant parameter object such as data type, dimensions, and storage class applicable to all the choice values, specified as a Simulink.Parameter object. You can override the specification when setting a choice value explicitly.

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

When using both Specification and Bank properties for a Simulink.VariantVariable object, the specification object must have storage class set to Auto and it must not use symbolic dimensions. For a variant parameter bank, use a Simulink.VariantBankCoderInfo object to specify code generation attributes.

Example: P = Simulink.VariantVariable('Specification','sp','Choices',{'V == 1',2,'V == 2',3});

Attributes:

GetAccess	public
SetAccess	public

Bank — Name of variant parameter bank

'' (default) | string scalar | character vector

Name of variant parameter bank (Simulink.VariantBank) object, specified as a string scalar 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 activation time set to startup 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: P = Simulink.VariantVariable('Bank','ParamBank','Choices',{'V == 1',2,'V == 2',3});

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	Determines whether the inputs are equal.
gt	Determines whether 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	Determines whether the first input is greater than or equal to the second input.
le	Determines whether 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	Determines whether the first input is less than the second input.
ne	Determines whether 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

Create Variant Parameters Programmatically Using Simulink.VariantVariable Class

This example shows you how to create variant parameters using the Simulink.VariantVariable class in the base workspace. To create the variant control and variant parameter objects in a data dictionary, see Add Entry to Design Data Section of Data Dictionary.

Create Variant Parameter

In the MATLAB® Command Window, define a variant control variable V using the Simulink.VariantControl class and set its value to 1. The default variant activation time for the variant control is update diagram.

V = Simulink.VariantControl('Value',1);

Create a variant parameter object by specifying the variant conditions and values for the choices.

Use V to specify a variant condition for each choice of the variant parameter. During simulation, the choice value that corresponds to the variant condition that evaluates to true becomes the active value of the parameter. Thus, the variant control V allows you to set one of the choice values as the active variant.

Since the value of V is 1, the condition V == 1 evaluates to true when you simulate the model and hence K1 is assigned a value of 3.5.

K1 = Simulink.VariantVariable('Choices',{'V == 1',3.5,'V == 2',8.3});

You can perform arithmetic and logical operations on the variant parameter object.

P = K1*3;

Specify Simulink.Parameter Object as Variant Parameter Value

You can assign a Simulink.Parameter object's name as the value of a variant parameter object, enabling you to define code generation settings for each variant parameter value. These Simulink.Parameter objects must be defined in the same workspace as the variant parameter. Additionally, all Simulink.Parameter objects used with a single variant parameter must have the same datatype, complexity, dimensions, and storage class attributes.

V = Simulink.VariantControl('Value',1);
spValue1 = Simulink.Parameter(3.5);
spValue1.CoderInfo.StorageClass = 'ImportedExtern';
spValue2 = Simulink.Parameter(8.3);
spValue2.CoderInfo.StorageClass = 'ImportedExtern';
K1 = Simulink.VariantVariable('Choices',{'V == 1','spValue1','V == 2','spValue2'});

Specify Default Value for Variant Parameter

To specify one of the choice values as a default value for the parameter, use the (default) keyword for the variant condition. Simulink® uses the default value for the variant parameter when none of the other variant conditions evaluate to true. When activation time is set to code compile, this default value is assigned in the #else condition. When activation time is set to startup, the value is assigned in the else condition in the generated code.

K2 = Simulink.VariantVariable('Choices',{'V == 1',3,'(default)',6});

Analyze Variant Parameter Values for Consistent Signal Attributes

When you specify a variant activation time other than update diagram for the Simulink.VariantControl, Simulink analyzes all choice values of the variant parameters for consistency of signal attributes such as datatype, dimensions, and complexity. Activation time also determines whether the generated code must contain only the active choice or both active and inactive choices.

Create a variant control variable V with variant activation time set to update diagram analyze all choices.

V = Simulink.VariantControl('Value',1,'ActivationTime','update diagram analyze all choices');
K4 = Simulink.VariantVariable('Choices',{'V == 1',int8(3),'V == 2',int8(7)});

If you add the choice value 5.1 to K4 and use K4 in a model, the model compilation fails because the data type of the choice is not of type int8.

K4 = setChoice(K4,{'V == 3',5.1});

Specify Common Code Generation Properties for Variant Parameter Values

If you intend to generate code for a model containing variant parameters, use a Simulink.Parameter object to define specifications such as data type, dimensions, and storage class for all the variant choices.

sp = Simulink.Parameter(int8([])); 
sp.CoderInfo.StorageClass = 'Custom';
sp.CoderInfo.CustomStorageClass = 'Define';
sp.CoderInfo.CustomAttributes.HeaderFile = 'vparam.h';

Define a variant control variable V using the Simulink.VariantControl class.

V = Simulink.VariantControl('Value',1);

Create a variant parameter and set the Specification property. This command defines all the choices to be of type int8 with the specified custom storage class attributes for code generation.

K3 = Simulink.VariantVariable('Specification','sp','Choices',{'V == 1',4,'V == 2',8});

Create Variant Parameter Values with Different Dimensions

The example shows you how to create a variant parameter with choice values of different dimensions. All other attributes, such as data type and complexity, must be the same across all choices. To generate code for variant parameters that have values with different dimensions, use Embedded Coder®. If you set the activation time of the associated Simulink.VariantControl object to code compile, Embedded Coder generates code for both active and inactive values of variant parameters.

In this example, the variant parameter kv1 has values with different dimensions and the variant activation time of the associated variant control variable object V is set to code compile. The storage class of kv1 is set to exported data scope (ExportedGlobal (Embedded Coder)) to generate code that reuses the variant parameter values that you specify. You can choose to generate code that imports variant parameter values and its dimensions from external code prior to code compilation by setting the storage class with imported data scope (ImportedExtern, ImportedExternPointer (Embedded Coder)).

% Variant parameter specification
spec = Simulink.Parameter();
spec.CoderInfo.StorageClass = 'ExportedGlobal';

% variant control variable
V = Simulink.VariantControl('Value',1,'ActivationTime','code compile');
 
% variant parameter 
choice1 = 'V == 1';
choice2 = 'V == 2';
choice3 = 'V == 3';
kv1 = Simulink.VariantVariable('Choices',...
    {choice1,[1, 2, 3, 4],choice2,[1, 2, 3, 4, 5],choice3,[1, 2, 3, 4, 5, 6]},...
    'Specification','spec');

When you generate code for a model that uses kv1, the code contains active and inactive values of kv1 with dimensions represented as symbols. All values are enclosed in C preprocessor conditionals #if and #elif. When you compile the code, Simulink® evaluates the preprocessor conditionals and preserves the code only for the active value of the variant parameter. For more information, see Compile Code Conditionally for All Values of Variant Parameters with Same and Different Dimensions (Embedded Coder).

Import Variant Parameter Values from External Code

This example shows you how to specify the choice values of variant parameters as Simulink.Parameter variables. Here, using Simulink.Parameter variables allow you to generate code that imports variant parameter values from your existing user-written code. Thus, you can reuse the values that your existing code defines. During code compilation, the generated code and the user-written code is integrated into a single executable.

% imported parameters
kv_hatchback = Simulink.Parameter(3);
kv_sedan = Simulink.Parameter(6);
kv_hatchback.CoderInfo.StorageClass = 'ImportedExtern';
kv_sedan.CoderInfo.StorageClass = 'ImportedExtern';

% variant control
V = Simulink.VariantControl('Value',1,'ActivationTime','startup');

% variant parameters
kv = Simulink.VariantVariable('Choices',{'V == 1','kv_hatchback',...
 'V == 2','kv_sedan'});

For more information, see Reuse Variant Parameter Values from Handwritten Code Using Simulink.Parameter Variables (Embedded Coder).

Group Variant Parameter Values in Code Using Variant Parameter Bank

This example shows you how to group variant parameters in the generated code by adding them to the same variant parameter bank (Simulink.VariantBank).

Create a variant parameter bank.

EngineParams = Simulink.VariantBank(Name='EngineParams',Description='Engine parameters',...
                                     VariantConditions={'V == EngType.Small','V == EngType.Big'});

Create a variant control variable V using the Simulink.VariantControl class. The Value property of this object allows you to select an active value for a variant parameter and the ActivationTime property allows you to specify a variant activation time. To use variant parameter banks, the activation time must be set up to startup. Use this variable to specify the variant condition expression for the choice values of a variant parameter.

Create two variant parameter objects K1 and K2 and associate them with the variant parameter bank EngineParams.

Use the name of the variant parameter bank to set the Bank property of a Simulink.VariantVariable object. The generated code groups the Simulink.VariantVariable objects that share the same Bank property in the same structure.

V = Simulink.VariantControl(Value=EngType.Small,ActivationTime='startup');
K1 = Simulink.VariantVariable(Choices={'V == EngType.Small',3,'V == EngType.Big',6},Bank='EngineParams');
K2 = Simulink.VariantVariable(Choices={'V == EngType.Small',[3, 6, 9],'V == EngType.Big',[5, 10, 15]},Bank='EngineParams');

To additionally specify code generation properties for a variant parameter bank, use the Simulink.VariantBankCoderInfo class.

Limitations

• The Value property of the variant control variable (Simulink.VariantControl) that determines the active value of a variant parameter must be an integer, an enumeration, a Simulink.Parameter object with value of type integer or enumeration, or a user-defined type that inherits from Simulink.Parameter.

• Only the values of the variant parameters change based on the variant condition that evaluates to true. Other properties, such as storage class, data types, and so forth, remain the same irrespective of the variant condition.

• Variant parameters can only be defined in a base workspace or a data dictionary.

• 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 with activation time set to startup, you can generate code for both active and inactive choices by installing Simulink Coder™ or Embedded Coder.

• For variant parameters with activation time set to code compile:

  • 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 with activation time set to startup 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).