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
creates an empty
variant parameter object.P
= Simulink.VariantVariable
creates
a variant parameter object as specified by one or more P
= Simulink.VariantVariable(Name,Value
)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
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. DefiningSimulink.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 thanSimulink.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. DefiningSimulink.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
Open Example
You have a modified version of this example. Do you want to open this example with your edits?
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)