Tune Mask Popup Parameters by Referencing an External Enumeration File
You can visualize the behavior of a Simulink® model under different conditions by tuning block parameter values. This example shows how to associate values with popup parameters and achieve code generation time tunability. Referencing an external enumeration file to tune a mask popup parameter allows you to:
Associate numeric values with the popup options.
Associate a variable with the popup parameter.
Simulate and generate code corresponding to the selected popup option.
Consider this example where a subsystem containing a Constant block is connected to an output port.
Associate External Enumeration File to Popup Parameter
An external enumeration file can have multiple members with different display names and values. When the enumeration file is associated with a popup parameter:
The display name of the enumeration member becomes the popup parameter option.
The enumeration member value becomes the value assigned to the popup parameter.
In this example, numeric values are associated with pop-up options from the enumerated file Xfactor.m
. The enumeration class of the file Xfactor
, is derived from
. The class has three enumeration members, Simulink.Mask.EnumerationBase
alpha
, beta
, and gamma
. These enumerated members have numeric values .001
, .0001
, and .00001
.
classdef XFactor < Simulink.Mask.EnumerationBase enumeration alpha(.001, 'alpha (.001)') beta (.0001, 'beta (.0001)') gamma(.00001,'gamma (.00001)') end end
Specify data type for numerical values associated with the enumeration member
In the generated code, the default data type for the enumeration member is double. Alternatively, you can also specify a data type for the enumeration members. For example, alpha (int32(0.001),'alpha (.001)')
. All members of the enumeration class must be of the same data type.
Associate Numeric Values to Popup Parameter Options
1. In the Mask Editor of the Tunable Popup Subsystem block, create a popup parameter named XFactorParam
.
2. In the Property editor, select the Reference external enumeration option and specify the name of the enumeration class that was created in the previous step. In this example, the name of the enumeration class is Xfactor
.
Note: The referencing enumeration class Xfactor
must be in the MATLAB® path.
Upon referencing the enumeration class file, the options for the popup parameter in the mask dialog box of the Subsystem block are populated with the display names in the enumeration file.
Reference the Popup Parameter in Child Blocks
The parameter value is evaluated as the enumeration member corresponding to the display name you select. For example, if you select alpha(.0001)
from the Parameters drop-down, the value of XFactorParam
is set to XFactor.alpha
. During model compilation, in order to get the numeric value corresponding to an option, Simulink creates an internal array that holds the value corresponding to each option. Therefore, when you select an option, the value corresponding to the option is selected from the array.
In this example, the array appears XFactorValues = {.001, .0001, .00001}
Note: To get the value corresponding to the selected option, use this format:
<enumerationClassName>Values(<ParameterName>)
enumerationClassName
is the name of the enumeration class, and ParameterName
is the name of the pop-up parameter that you specified in the mask editor.
In this example, the value of the Constant parameter inside the subsystem is set as XFactorValues(XFactorParam)
. During model compilation, XFactorValues(XFactorParam)
evaluates to XFactorValues(XFactor.alpha)
, thus setting the value of the Constant parameter to .001
.
You can customize a name for the array in the enumeration file as the return value of the getValueArrayName()
function.
classdef XFactor < Simulink.Mask.EnumerationBase enumeration alpha(.001, 'alpha (.001)') beta (.0001, 'beta (.0001)') gamma(.00001,'gamma (.00001)') end methods(Static) function valueArrayName = getValueArrayName() valueArrayName = 'customValueArrayName'; end end end
Tune Parameter During Simulation and Code Generation
Change the value of the parameter in the dialog between alpha (0.001)
, beta (0.0001)
, and gamma (0.00001)
and observe that during simulation, the value corresponding to the selected option appears as the output of the simulation.
You can generate code using Simulink Coder™ or Embedded Coder™. In the generated code:
The value array
XFactorValues
is generated in themodelname.c
file.
const real_T XFactorValues[3] = { 0.001, 0.0001, 1.0E-5 } ;
Enumeration is generated in the code corresponding to the referenced enumeration file.
typedef enum { XFactor_alpha = 1, /* Default value */ XFactor_beta, XFactor_gamma } XFactor;
The mask parameter
(XFactorParam)
appears in the parameter structure.
/* Parameters (default storage) */ struct P_slexMaskTunablePopupExample_T_ { XFactor TunablePopup_XFactorParam;/* Mask Parameter: TunablePopup_XFactorParam * Referenced by: '<S1>/Constant' */ };
Tunable variable
XFactorParam
is referenced while generating the output. You can specify different values toXFactorParam
and thus tunability is achieved.
/* Model step function */ void slexMaskTunablePopupExample_step(void) { /* Outport: '<Root>/Out1' incorporates: * Constant: '<S1>/Constant' */ slexMaskTunablePopupExample_Y.Out1 = XFactorValues[(int32_T) slexMaskTunablePopupExample_P.TunablePopup_XFactorParam - 1]; }
Create and Associate Variables Using the Mask Dialog
When the default parameter behavior in the code generation optimization is inlined, all the parameters are inlined in the generated code. To achieve tunability for a specific parameter, create a variable of type Simulink.Parameter
with specific storage class (anything other than Auto) in the workspace and associate with the mask popup parameter.
1. Open the mask dialog. Click the action widget (...).
2. You can associate an existing variable with the popup parameter or create the variable in one of the available locations and associate with the popup parameter.
After associating the variable with the popup parameter, the variable appears next to the popup option.
The value of the associated variable and the pop-up value are always synchronized. For example, if you change the popup option from alpha (.001)
to beta (.0001)
, the workspaceVar
is updated to XFactor.beta
. Similarly, when you change the value of the variable, the value of the parameter reflects the change in the mask dialog.
Generate Code with the Associated Variable
The associated variable value appears in the parameter structure corresponding to the tunable popup parameter.
/* Block parameters (default storage) */ P_slexMaskTunablePopupExample_T slexMaskTunablePopupExample_P = { /* Variable: workspaceVar * Referenced by: '<S2>/Constant' */ XFactor_alpha, };
The associated variable is referenced in the step function to generate output.
/* Model step function */ void slexMaskTunablePopupExample_step(void) { /* Outport: '<Root>/Out2' incorporates: * Constant: '<S2>/Constant' */ slexMaskTunablePopupExample_Y.Out2 = XFactorValues[(int32_T) slexMaskTunablePopupExample_P.workspaceVar - 1]; }
Use APIs to Reference External Enumeration File
Create a type option object using this API.
enumObj =
Simulink.Mask.EnumerationTypeOptions(ExternalEnumerationClass,
'<enumName>')
Create an instance of Simulink.Mask.EnumerationTypeOptions
to parse the information from the enumeration file into the object enumObj
.
Example >> enumObj = Simulink.Mask.EnumerationTypeOptions('ExternalEnumerationClass', 'XFactor')
enumObj = EnumerationTypeOptions with properties: ExternalEnumerationClass: 'XFactor' EnumerationMembers: [1*3 Simulink.Mask.EnumerationMembers]
>> enumObj.EnumerationMembers(1)
ans = EnumerationMembers with properties: MemberName: 'alpha' DescriptiveName: 'alpha (.001)' Value: 0.001
Associate the enum object with the Type Options attribute.
maskobj = Simulink.Mask.create(<blockName>); maskobj.addParameter('Type','popup','TypeOptions', enumObj );
If a mask parameter already exists, use the these APIs.
maskobj = Simulink.Mask.get(<blockName>); paramHandle = maskobj.getParameter('<parameterName>'); paramHandle.TypeOptions = enumObj
Use this command to associate the variable to the value of the parameter.
set_param(<blockName>, '<ParameterName>', 'workspaceVar')
Associate Enumeration File Derived from Simulink.IntEnumType
If you have an existing enumeration class derived from Simulink.IntEnumType
, you can use the enumeration file to associate numeric values to the popup parameter instead of creating a new enumeration class derived from Simulink.Mask.EnumerationBase
. To associate enumeration file derived from Simulink.IntEnumType
, follow these steps.
classdef Color < Simulink.IntEnumType enumeration red(1) green(100) blue(1000) end methods(Static) function aOut = addClassNameToEnumNames() aOut = false; end end end
1. Specify the name of the enumeration class.
2. The popup options will be populated with enumeration members prefixed with the enumeration class name.
3. Set the Constant parameter value to the popup parameter XFactorParam
.