This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

Add Constraints to Mask Parameters

A mask can contain parameters that accept user-input value. You can provide the input values for these mask parameters from the mask dialog box. You can add constraints to the mask parameters to ensure that the input value for the mask parameter is within a desired specification. If the input value is not within the desired specification, the simulation can generate error.

. To add mask constraints without having to write validation code (Initialize Mask, Mask Callback Code), use the Constraint Manager option available in the Mask Editor.

Constraints are of type:

  • Parameter Constraint — Associated with one or more Edit type mask parameters. You can create these constraints in the mask or save them as a MAT file. Multiple block masks can share a parameter constraint saved as a MAT file.

  • Cross Parameter Constraint — Applied among two or more Edit type mask parameters.

Create Parameter Constraints

Consider the model masking_example. This model contains two Edit type mask parameters, Slope and Intercept.

You can specify values for the Slope and Intercept in the mask dialog box. To restrict the input value (for example, data type) for the Slope and Intercept parameters, create a parameter constraint with the required rule and associate it with the Slope and Intercept parameters. To restrict the input value such that the value of Slope is greater than the input value of the Intercept parameter, you can create a cross-parameter constraint between these two parameters.

  1. Open the model masking_example. This model contains a masked Subsystem block with two Edit type mask parameters, Slope (m) and Intercept (b).

  2. Right-click the masked Subsystem block (mx + b) and select Mask > Edit Mask.

  3. In the Mask Editor dialog box, click the Parameters & Dialog tab.

  4. Click Constraint Manager at the bottom left of the Mask Editor. Alternatively, select any edit parameter and then in the Property editor, from the Constraint drop-down menu, select Add New Constraint. The Constraint Manager window appears.

    Constraint Manager has two panes, Parameter Constraints and Cross Parameter Constraints. By default, the Parameter Constraints pane opens. The constraints that you create using the Parameter Constraints pane can be associated with Edit type mask parameters.

  5. Click Create Constraint. A constraint with a default name (Constraint_1) is created and properties related to this constraint are displayed. To change the constraint name, edit the Name field. The constraint name must be a valid MATLAB® name. By default, a rule (Rule_1) with Data type as double is added when a new constraint is created. You can modify the attributes of the rule. You can also add more rules to a constraint by clicking Add Rule.

  6. To save the new constraint to a MAT file, select the Save constraint to MAT file check box. This enables the Mat-file Name field and the Browse button.

    Note

    Saving a constraint to a MAT file makes it independent of the mask so that multiple masks can share that constraint. You can skip this action if you want the constraint to be tagged to the specific mask that you are editing.

  7. Enter the MAT file name in the Mat-file Name field or click Browse to create a new MAT file or select one from the local directory.

  8. Specify attributes for the rule. This table shows the rule attributes and acceptable values.

    Rule AttributeAttribute ValueDescription

    Data type

    double, single, numeric, integer, int8, uint8, int16, uint16, int32, uint32, boolean, enum, fixdt, string

    Specify the acceptable data type of the mask parameter value. For example, if the data type specified is uint8, the acceptable value is in the range of uint8, that is, 0–255.

    Complexity

    real, complex

    Specify if the mask parameter value can be a real or complex number.

    Dimensions

    scalar, row vector, column vector, 2-D matrix, n-D matrix

    Specify the acceptable dimensions for the mask parameter.

    Sign

    positive, negative, zero

    Specify if the input value can be positive, negative, or zero.

    Finiteness

    finite, inf, -inf, NaN

    Specify the acceptable finiteness of mask parameter value.

    Range

    Minimum, Maximum

    Specify the acceptable range of mask parameter value.

    Custom Constraint

    Valid MATLAB expression

    Specify custom constraint for the mask parameter using a valid MATLAB expression. You can use the value token to parameterize the expression. During validation, the evaluated value of the parameter replaces the value token. For example, if the MATLAB expression for a constraint is value > 100 and is associated with the Edit type mask parameter, Parameter1, the MATLAB expression evaluates as Parameter1 > 100.

    Custom Error Message

    Character vector

    Specify a custom error message for the custom constraint. You can specify the error message as character vector or as a message catalog ID.

    A constraint can contain single or multiple rules. In case of multiple rules, value of associated parameter must satisfy at least one rule. If multiple attributes are selected from a rule category, the parameter value must satisfy at least one attribute from each category. For example, if a constraint rule contains scalar and row vector as the Dimension attributes and positive and zero as the Sign attributes, the value of parameter must be (scalar or row vector) and (positive or zero).

  9. Optionally, to add more rules to the constraints, click Add Rule. A new rule section with rule attribute opens.

  10. Click Apply. A parameter constraint with specified rules is now created. You can associate this constraint with one or many Edit type mask parameters.

  11. Optionally, to delete a constraint, select the constraint in the Constraint Name field available in the Parameter Constraints pane and click Delete Constraint.

Consider the Parameter Constraint model in slexMaskConstraints. This model contains a masked UDP Send block that has parameter constraints, constraint_1 and constraint_2. The constraint_1 is associated with Remote IP Port parameter while the constraint_2 is associated with the SampleTime parameter.

Shared Parameter Constraints

You can create and save parameter constraints in a MAT file. You can save a constraint in a MAT file either from the Mask Editor or programmatically. Multiple block masks can share a parameter constraint if the constraint is saved in a MAT file. A shared constraint is listed in the Property editor section in the format <MATFileName>:<ConstraintName>. You can select any available constraint as required and associate it with an Edit parameter. For more information, see Associate Constraint to a Parameter.

While creating shared constraints it is recommended that you:

  • Save constraints to MAT files that are in the MATLAB path.

  • Provide meaningful names to constraints so that other users can understand the nature of the constraint easily.

Constraints associated to an Edit parameter from a MAT file (shared constraints) are validated during edit-time and simulation.

To create a shared constraint, select the Save constraint to MAT file check box available in the Constraint Manager and specify the MAT file name. For more information, see Create Parameter Constraints.

Note

If you clear the Save constraint to MAT file check box of a shared constraint that is associated with an Edit parameter, a copy of the constraint is created within the context of that particular mask. You can now make changes to the attributes of that constraint without affecting the original shared constraint saved in the MAT file. Note that the original shared constraint is still in the MAT file and is available for other users.

Save and Load Constraints Programmatically

You can save constraints in a MAT file and load constraints from a MAT file programmatically.

To save a constraint in a MAT file:

uint16Constraint = Simulink.Mask.Constraints;
uint16Constraint.Name = 'uint16Constraint';
uint16Constraint.addParameterConstraintRule('DataType', 'uint16');
save('constraintList.mat', 'uint16Constraint','-append');  %this will append the 
constraint uint16Constraint in the mat file
save('constraintList.mat', 'uint16Constraint') % this will clear all the 
content of 
the mat file and write just 'uint16Constraint' into the mat file.

Note

It is recommended that the constraint name (for example, uint16Constraint.Name = 'uint16Constraint') and the variable used for storing the constraint (for example, uint16Constraint = Simulink.Mask.Constraints) have the same name.

To load a constraint from a MAT file:

myConstraints = load(‘constraintList’) //this will load the constraint into 
the variable 'myConstraints'

For more information on working with constraints programmatically, see Simulink.Mask and Simulink.Mask.Constraints.

Associate Constraint to a Parameter

You can associate constraints to any Edit mask parameters. Associating a constraint to an Edit parameter ensures that the input value for the mask parameter is within a desired specification.

  1. Open the model masking_example. This model contains a masked Subsystem block with two Edit type mask parameters, Slope (m) and Intercept (b).

  2. Right-click the masked Subsystem block (mx + b) and select Mask > Edit Mask.

  3. Click the Parameters & Dialog tab and select any Edit parameter.

  4. In the Property editor pane, from the Constraint drop-down menu, select an available constraint. Here, the constraints available in a MAT file are shown as <MATFileName>:<Constraint name>. The constraints available within the mask are shown as <Constraint Name>. If no constraints are shown in the drop-down menu, click Add New Constraint to add a new one from Constraint Manager or click Browse and Add New Constraint to add constraints saved in MAT files. You can also type the constraint name to associate them to a parameter.

  5. Click Apply. The selected constraint is now associated to the Edit parameter.

Create Cross-Parameter Constraint

The cross-parameter constraints allow you to create constraints among Edit type mask parameters of a block. You can use the Cross Parameter Constraints pane to create this type of constraints. As a best practice, create the cross-parameter constraints between related mask parameters. For example, between slope and intercept, or upper bound and lower bound of the Integrator block.

  1. Open the model masking_example. This model contains a masked Subsystem block with two Edit type mask parameters, Slope (m) and Intercept (b).

  2. Right-click the masked Subsystem block (mx + b) and select Mask > Edit Mask.

  3. In the Mask Editor dialog box, click the Parameters & Dialog tab.

  4. Click Constraint Manager at the bottom left of the Mask Editor. The Constraint Manager opens.

  5. Click the Cross Parameter Constraints tab.

  6. Click Create Constraint. A new cross-parameter constraint is created with a default name (Constraint_1). You can change the constraint name.

  7. Specify these values for the constraints:

    1. Name - Specify the name of the cross-parameter constraint.

    2. MATLAB Expression - Specify a valid MATLAB expression. This expression is evaluated during edit-time and simulation. For example, Slope < Intercept.

    3. ErrorMessage - Specify the error message to be displayed when the constraint rule is not met. If no error message is specified, a default error message is displayed.

  8. Click OK. Cross-parameter constraint with specified rules is now created.

Consider the Cross-Parameter Constraint model in slexMaskConstraints. This model contains a masked Integrator block that has a cross-parameter constraint (LimitConstraint). This cross-parameter constraint is applied among mask parameters using the MATLAB expression:

(UpperSaturationLimit > LowerSaturationLimit) && isequal(class (UpperSaturationLimit), class(LowerSaturationLimit), class(InitialCondition)).

Related Topics