Simulink.VariantControl Class
Namespace: Simulink
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 choices of
variant blocks and variant parameters during simulation.
Creation
creates a variant control variable object with no value and
variantControlVariable
= Simulink.VariantControl'ActivationTime'
set to 'update diagram'
.
creates a variant control variable object as specified by variantControlVariable
= Simulink.VariantControl(Name,Value
)Name,Value
pair
arguments. Using this syntax, you create an object and associate its value with a variant
activation time.
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: 'Value', 1, 'ActivationTime', 'update
diagram'
Value
— Value of variant control variable object
scalar variable | enumerated type | Simulink.Parameter
| user-defined type that inherits from
Simulink.Parameter
Value of variant control variable object, specified as a scalar variable, an
enumerated type, a Simulink.Parameter
object with value of type
integer or enumeration, or a user-defined type that inherits from
Simulink.Parameter
.
When Value
is set to a Simulink.Parameter
object already used in the model or in another variant control object, use one of
these syntaxes to avoid a compile-time
error.
V = Simulink.VariantControl('Value',Simulink.Parameter(1));
P = Simulink.Parameter(1);
V = Simulink.VariantControl('Value',copy(P));
Example: 'Value',1
Example: V =
Simulink.VariantControl('Value',Simulink.Parameter(1));
Example: P = Simulink.Parameter(1); V =
Simulink.VariantControl('Value',copy(P));
ActivationTime
— Activation time of active value
'update diagram'
(default) | 'update diagram analyze all choices'
| 'code compile'
| 'startup'
Simulink® can set active choice of the variant blocks or 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 choice or both active and inactive choices. The property also determines whether to analyze all the choices 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 choices for incompatibilities in signal attributes. It generates code only for the active choice.'update diagram analyze all choices'
–– Simulink analyzes both active and inactive choices for incompatibilities in signal attributes, however it generates code only for the active choice.'code compile'
–– Simulink analyzes both active and inactive choices of variant blocks or variant parameters for incompatibilities in signal attributes and it also generates code for both active and inactive choices. The choices 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 choices of variant blocks and variant parameters for incompatibilities in signal attributes and it also generates code for both active and inactive choices. The choices are enclosed in regularif
conditions inside themodel_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
Examples
Simulink.VariantControl Variables for Coherent Switching of Choices in Variant Blocks
You can associate a variant control variable of type Simulink.VariantControl
with a variant activation time. Simulink.VariantControl
variant control variables help you switch variant elements such as blocks and parameters coherently.
Consider a group of blocks that represents a design choice, with each block having the same variant control variable of type Simulink.VariantControl
. If you set the variant activation time of these blocks to inherit from Simulink.VariantControl
, the blocks inherit the activation time from the variant control variable. As a result, all the blocks have the same activation time and are activated simultaneously to generate rational simulation results and valid code.
You can define Simulink.VariantControl
type of control variables in storage locations as listed in Storage Locations for Variant Control Variables (Operands) in Variant Blocks.
Open the slexVariantSubsystems
model.
open_system('slexVariantSubsystems');
In the block parameters dialog box of the Controller
block:
1. Specify the variant controls, V == 1
and V == 2
.
set_param('slexVariantSubsystems/Controller/Linear Controller', 'VariantControl', 'V==1') set_param('slexVariantSubsystems/Controller/Nonlinear Controller', 'VariantControl', 'V==2')
2. Set Variant activation time to inherit from Simulink.VariantControl
to inherit the activation time from V
.
set_param('slexVariantSubsystems/Controller', 'VariantActivationTime', 'inherit from Simulink.VariantControl')
In the base workspace, define a Simulink.VariantControl
object, V
. Set its value to 1
, variant activation time to update diagram
, and then simulate the model.
V = Simulink.VariantControl('Value', 1, 'ActivationTime', 'update diagram')
V = VariantControl with properties: Value: 1 ActivationTime: 'update diagram'
During simulation, the Controller
block inherits the update diagram
activation time from V
and the Linear Controller
block becomes active.
Double-click the Controller
block to see the active choice.
sim ('slexVariantSubsystems');
If you change the value of V
to 2
, the Nonlinear Controller
block becomes active during simulation. You can change the value of V
using this command or from Simulink.VariantControl
dialog box.
V.Value = 2;
sim ('slexVariantSubsystems');
If you change the variant activation time of V
to update diagram analyze all choices
, the Controller
block inherits the update diagram analyze all choices
activation time from V
. You can observe the inherited activation time using CompiledVariantActivationTime
.
V.ActivationTime = 'update diagram analyze all choices'; sim ('slexVariantSubsystems'); get_param('slexVariantSubsystems/Controller', 'CompiledVariantActivationTime')
ans = 'update diagram analyze all choices'
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')
Enumerated Types to Improve Code Readability of Variant Control Variables of Variant Parameters
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: '' Bank: '' 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: '' Bank: '' 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 methods (Static) function retVal = addClassNameToEnumNames() % ADDCLASSNAMETOENUMNAMES Specifies whether to add the class name % as a prefix to enumeration member names in generated code. % Return true or false. % If you do not define this method, no prefix is added. retVal = true; end 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
, oruint16
, or by subclassingSimulink.IntEnumType
These enumerations are also supported when permanently stored in a Simulink® data dictionary. See Enumerations in Data Dictionary.
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 Parameters.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 (Simulink 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}); K2 = Simulink.VariantVariable('Choices',{'V == 1',4.5,'V == 2',9.5});
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 property to VSS_MODE
.
V = Simulink.VariantControl('Value',copy(VSS_MODE),'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 the Simulink.VariantControl
dialog box.
V.Value.Value=2;
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 (Simulink 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_ */ % % /*
Custom Data Class Objects as Values of Simulink.VariantControl
Objects
Set the value of a Simulink.VariantControl
object to an object of a user-defined data class that derives from Simulink.Parameter
. The user-defined class package that contains the class definition must be available on the MATLAB® search path. Data objects that you create from your package can use the storage classes that the package defines. For an example that shows how to create a data class in a package, see Define Data Classes.
Explore the Model
In this example, the +myPackage
folder is a user-defined data class package folder that contains the class folder @myExParameter
. The class folder contains the class definition file myExParameter.m
and the class derives from Simulink.Parameter
. The csc_registration.m
file contains the custom storage class defined for this package using the Custom Storage Class Designer.
open_system("slexVariantParameters");
The
slexVariantParameters
model uses two variant parametersK1
andK2
, and aSimulink.VariantControl
objectV
, that are defined in the base workspace.Double-click the variant control object
V
in the base workspace to open theSimulink.VariantControl
dialog box.Select the custom class
myPackage.myExParameter
from the Value type list.In the Value box, enter
1
as the value of the variant control.From the Data type list, select
int32
and from the Activation time list, selectstartup
.In the Code Generation tab, select the custom storage class
myPackage_ExportedGlobal
defined in the package.
Generate code from the model. For information on how to generate code, see Generate Code Using Embedded Coder (Embedded Coder).
The generated header file myParams.h
contains the extern
declaration for the variable V
and the generated file myParams.c
contains the definition of the variable according to the settings in the custom storage class definition.
/* myParams.h */ /* Declaration for custom storage class: myPackage_ExportedGlobal */ extern int32_T V; /* myParams.c */ /* Exported data definition */ /* Definition for custom storage class: myPackage_ExportedGlobal */ int32_T V = 1;
Limitations
Using a
Simulink.VariantControl
object directly as an S-Function parameter in a noninlined S-Function block is not supported for code generation.Simulink.VariantControl
value must be an integer, an enumeration, aSimulink.Parameter
with value of type integer or enumeration, or a user-defined type that inherits fromSimulink.Parameter
.
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
For more information on code generation with variant parameters, see Options to Represent Variant Parameters in Generated Code (Embedded Coder).
Version History
Introduced in R2021aR2024b: Error reported when Simulink.VariantControl
uses
Simulink.Parameter
object already used in model or in another variant
control object
Simulink reports a compile-time error when you try to set the value of a
Simulink.VariantControl
object to a Simulink.Parameter
object that is already used in the model or in another variant control object.
To avoid the error, set the value of a Simulink.VariantControl
object
by creating a separate Simulink.Parameter
object or by creating a copy of
an existing Simulink.Parameter
object using the copy
method. For example:
P = Simulink.Parameter(1);
V = Simulink.VariantControl('Value',copy(P));
or
V = Simulink.VariantControl('Value',Simulink.Parameter(1));
R2024a: Simulink.VariantControl
object does not support Simulink.Parameter
object with slexpr
or nonscalar
values
The Simulink.VariantControl
object does not support setting its
Value
property to a Simulink.Parameter
object with Value
set to the slexpr
function or a nonscalar value.
See Also
Comando de MATLAB
Ha hecho clic en un enlace que corresponde a este comando de MATLAB:
Ejecute el comando introduciéndolo en la ventana de comandos de MATLAB. Los navegadores web no admiten comandos de MATLAB.
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)