Tune Mask Popup Parameters by Referencing an External Enumeration File

Open Model

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 Simulink.Mask.EnumerationBase. The class has three enumeration members, 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 the modelname.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 to XFactorParam 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.