Main Content

Create Model Advisor Check for Model Configuration Parameters

To verify the configuration parameters for your model, you can create a configuration parameter check.

Decide which configuration parameter settings to use for your model. If desired, review the modeling guidelines:

  1. Create an XML data file containing the configuration parameter settings you want to check. You can use Advisor.authoring.generateConfigurationParameterDataFile or manually create the file yourself.

  2. Register the model configuration parameter check using an sl_customization.m file.

  3. Run the check on your models.

Create a Data File for a Configuration Parameter Check

This example shows how to create a data file that specifies configuration parameter values in the Diagnostics pane. A custom check warns when the configuration parameters values do not match the values defined in the data file.

Open the model vdp by entering:

openExample('simulink_general/VanDerPolOscillatorExample')

Right-click in the model window and select Model Configuration Parameters. In the Diagnostics pane, set the configuration parameters as follows:

  • Algebraic loop to none

  • Minimize algebraic loop to error

  • Block Priority Violation to error

Use the Advisor.authoring.generateConfigurationParameterDataFile function to create a data file specifying configuration parameter constraints in the Diagnostics pane. Also, to create a check with a fix action, set FixValue to true. At the command prompt, type:

model='vdp';
dataFileName = 'ex_DataFile.xml';
Advisor.authoring.generateConfigurationParameterDataFile(dataFileName,...
model, 'Pane', 'Diagnostics', 'FixValues', true);

In the Command Window, select ex_DataFile.xml. The data file opens in the MATLAB® editor.

  • The Minimize algebraic loop (ArtificialAlgebraicLoopMsg) configuration parameter tagging specifies a value of error with a fixvalue of error. When you run the configuration parameter check using ex_DataFile.xml, the check fails if the Minimize algebraic loop setting is not error. The check fix action modifies the setting to error.

  • The Block Priority Violation (BlockPriorityViolationMsg) configuration parameter tagging specifies a value of error with a fixvalue of error. When you run the configuration parameter check using ex_DataFile.xml, the check fails if the Block Priority Violation setting is not error. The check fix action modifies the setting to error.

In ex_DataFile.xml, edit the Algebraic loop (AlgebraicLoopMsg) parameter tagging so that the check warns if the value is none. Because you are specifying a configuration parameter that you do not want, you need a NegativeModelParameterConstraint. Also, to create a subcheck that does not have a fix action, remove the line with <fixvalue> tagging. The tagging for the configuration parameter looks as follows:

<!-- Algebraic loop: (AlgebraicLoopMsg)-->
    <NegativeModelParameterConstraint>
        <parameter>AlgebraicLoopMsg</parameter>
        <value>none</value>
    </NegativeModelParameterConstraint>

In ex_DataFile.xml, delete the lines with tagging for configuration parameters that you do not want to check. The data file ex_DataFile.xml provides tagging only for Algebraic loop, Minimize algebraic loop, and Block Priority Violation. For example, ex_DataFile.xml looks similar to:

<?xml version="1.0" encoding="utf-8"?>
<customcheck xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"     
xsi:noNamespaceSchemaLocation="http://www.w3schools.com 
MySchema.xsd">
     <checkdata>       
     <!-- Algebraic loop: (AlgebraicLoopMsg)-->
        <NegativeModelParameterConstraint>
            <parameter>AlgebraicLoopMsg</parameter>
            <value>none</value>
        </NegativeModelParameterConstraint>
    <!--Minimize algebraic loop: (ArtificialAlgebraicLoopMsg)-->
        <PositiveModelParameterConstraint>
            <parameter>ArtificialAlgebraicLoopMsg</parameter>
            <value>error</value>
            <fixvalue>error</fixvalue>    
        </PositiveModelParameterConstraint>
    <!--Block priority violation: (BlockPriorityViolationMsg)-->
        <PositiveModelParameterConstraint>
            <parameter>BlockPriorityViolationMsg</parameter>
            <value>error</value>
            <fixvalue>error</fixvalue>
        </PositiveModelParameterConstraint>
    </checkdata>
</customcheck>

Verify the data syntax with Advisor.authoring.DataFile.validate. At the command prompt, type:

dataFile = 'ex_DataFile.xml'; 
msg = Advisor.authoring.DataFile.validate(dataFile); 

if isempty(msg)     
    disp('Data file passed the XSD schema validation.'); 
else 
    disp(msg); 
end

Create Check for Diagnostics Pane Model Configuration Parameters

This example shows how to create a check for Diagnostics pane model configuration parameters using a data file and an sl_customization.m file. First, you register the check using an sl_customization.m file. Using ex_DataFile.xml, the check warns when:

  • Algebraic loop is set to none

  • Minimize algebraic loop is not set to error

  • Block Priority Violation is not set to error

The check fix action modifies the Minimize algebraic loop and Block Priority Violation parameter settings to error.

The check uses the ex_DataFile.xml data file created in Create a Data File for a Configuration Parameter Check.

Close the Model Advisor and your model if either are open.

Use the following sl_customization.m file to specify and register check Example: Check model configuration parameters.

function sl_customization(cm)

% register custom checks.
cm.addModelAdvisorCheckFcn(@defineModelAdvisorChecks);


%% defineModelAdvisorChecks
function defineModelAdvisorChecks
    
 rec = ModelAdvisor.Check('com.mathworks.Check1');
	rec.Title = 'Example: Check model configuration parameters';
	rec.setCallbackFcn(@(system)(Advisor.authoring.CustomCheck.checkCallback...
                                        (system)), 'None', 'StyleOne');
	rec.TitleTips = 'Example check for model configuration parameters';
	
	% --- data file input parameters
	rec.setInputParametersLayoutGrid([1 1]);
	inputParam1 = ModelAdvisor.InputParameter;
	inputParam1.Name = 'Data File';
	inputParam1.Value = 'ex_DataFile.xml';
	inputParam1.Type = 'String';
	inputParam1.Description = 'Name or full path of XML data file.';
	inputParam1.setRowSpan([1 1]);
	inputParam1.setColSpan([1 1]);
	rec.setInputParameters({inputParam1});

	% -- set fix operation
	act = ModelAdvisor.Action;
	act.setCallbackFcn(@(task)(Advisor.authoring.CustomCheck.actionCallback...
                                                     (task)));
	act.Name = 'Modify Settings';
	act.Description = 'Modify model configuration settings.';
	rec.setAction(act);
    
	mdladvRoot = ModelAdvisor.Root;
	mdladvRoot.publish(rec,'Demo');
Note that model configuration parameter settings checks must use the setCallbackFcn type of StyleOne.

Create the Example: Check model configuration parameters. At the command prompt, enter:

Advisor.Manager.refresh_customizations

Open the model vdp by entering:

openExample('simulink_general/VanDerPolOscillatorExample')

Right-click in the model window and select Model Configuration Parameters. In the Diagnostics pane, set the configuration parameters as follows:

  • Algebraic loop to none

  • Minimize algebraic loop to warning

  • Block Priority Violation to warning

In the Modeling tab, select Model Advisor to open the Model Advisor.

In the left pane, select DemoExample: Check model configuration parameters. In the right pane, Data File is set to ex_DataFile.xml.

Click Run Checks. The Model Advisor check warns that the configuration parameters are not set to the values specified in ex_DataFile.xml. For configuration parameters with positive constraint tagging (PositiveModelParameterConstraint), the recommended values are obtained from the value tagging. For configuration parameters with negative constraint tagging (NegativeModelParameterConstraint), the values not recommended are obtained from the value tagging.

  • Algebraic loop(AlgebraicLoopMsg) — the ex_DataFile.xml tagging does not specify a fix action for AlgebraicLoopMsg. The subcheck passes only when the setting is not set to none.

  • Minimize algebraic loop(ArtificialAlgebraicLoopMsg) — the ex_DataFile.xml tagging specifies a subcheck with a fix action for ArtificialAlgebraicLoopMsg that passes only when the setting is error. The fix action modifies the setting to error.

  • Block priority violation(BlockPriorityViolationMsg) — the ex_DataFile.xml tagging specifies a subcheck with a fix action for BlockPriorityViolationMsg that does not pass when the setting is warning. The fix action modifies the setting to error.

In the toolstrip, click Fix. The Model Advisor updates the configuration parameters for Block priority violation and Minimize algebraic loop.

Run the Demo > Example: Check model configuration parameters check again. The check warns because Algebraic loop is set to none.

In the right pane of the Model Advisor window, use the Algebraic loop (AlgebraicLoopMsg) link to edit the configuration parameter. Set Algebraic loop to warning or error.

Run the check a final time. The check passes.

Data File for Configuration Parameter Check

You use an XML data file to create a configuration parameter check. To create the data file, you can use Advisor.authoring.generateConfigurationParameterDataFile or manually create the file yourself. The data file contains tagging that specifies check behavior. Each model configuration parameter specified in the data file is a subcheck. The structure for the data file is as follows:

<?xml version="1.0" encoding="utf-8"?>
<customcheck xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:noNamespaceSchemaLocation="http://www.w3schools.com 
MySchema.xsd">
    <messages>    
        <Description>Description of check</Description>    
        <PassMessage>Pass message</PassMessage>
        <FailMessage>Fail message</FailMessage>
        <RecommendedActions>Recommended action</RecommendedActions>        
    </messages>
    <checkdata>
    <!--Command line name of configuration parameter-->
        <PositiveModelParameterConstraint>
            <parameter>Command-line name of configuration parameter</parameter>
            <value>Value that you want configuration parameter to have</value>
            <fixvalue>Specify value for a fix action</fixvalue>
            <dependson>ID of configuration parameter subcheck that must pass 
                    before this subcheck runs</value>    
        </PositiveModelParameterConstraint>
    <!-- Command line name of configuration parameter-->
        <NegativeModelParameterConstraint>
            <parameter>Command line name of configuration parameter</parameter>
            <value>Value that you do not want configuration parameter to have</value>
            <fixvalue>Specify value for a fix action</fixvalue>
            <dependson>ID of configuration parameter subcheck that must pass 
                    before this subcheck runs</value>
        </NegativeModelParameterConstraint>
     </checkdata>
</customcheck>

The <messages> tag contains:

  • Description — (Optional) Description of the check. Displayed in Model Advisor window.

  • PassMessage — (Optional) Pass message displayed in Model Advisor window.

  • FailMessage — (Optional) Fail message displayed in Model Advisor window.

  • RecommendedActions — (Optional) Recommended actions displayed in Model Advisor window when check does not pass.

Note

The <messages> tag is optional. Advisor.authoring.generateConfigurationParameterDataFile does not generate <messages> tagging.

In the <checkdata> tag, the data file specifies two types of constraints:

  • PositiveModelParameterConstraint — Specifies the configuration parameter setting that you want.

  • NegativeModelParameterConstraint — Specifies the configuration parameter setting that you do not want.

Within the tag for each of the two types of constraints, for each configuration parameter that you want to check, the data file has the following tags:

  • parameter — Specifies the configuration parameter that you want to check. The tagging uses the command line name for the configuration parameter. For example:

    <PositiveModelParameterConstraint>
    <parameter>BlockPriorityViolationMsg</parameter>
</PositiveModelParameterConstraint>
<NegativeModelParameterConstraint>
    <parameter>AlgebraicLoopMsg</parameter>
</NegativeModelParameterConstraint>

  • value — Specifies the setting(s) for the configuration parameter. You can specify more than one value tag.

    When using PositiveModelParameterConstraint, value specifies the setting(s) that you want for the configuration parameter. For NegativeModelParameterConstraint, value specifies the setting(s) you that do not want for the configuration parameter.

    You can specify the value using a format in this table.

    TypeFormatExample
    Scalar value 
    <value>xyz</value>

    In this example, constraint NegativeModelParameterConstraint warns when the configuration parameter settings for configuration parameter is not error or none.

    <NegativeModelParameterConstraint>
    <value>error</value>
    <value>none</value>
</NegativeModelParameterConstraint>

    Structure or object 
    <value>
    <param1>xyz</param1>
    <param2>yza</param2>
</value>

    In this example, constraints PositiveModelParameterConstraint warns when the configuration parameter settings are not a valid structure:

    <PositiveModelParameterConstraint>
    <value>
        <double>a</double>
        <single>b</single>
    </value>
</PositiveModelParameterConstraint>

    Array 
    <value>
    <element>value</element>
    <element>value</element>
</value>

    In this example, constraint NegativeModelParameterConstraint warns when the configuration parameter settings are an invalid array:

    <NegativeModelParameterConstraint>
    <value>
        <element>A</element>
        <element>B</element>   
    </value>
</NegativeModelParameterConstraint>

    Structure Array 
    <value>
    <element>
        <param1>xyz</param1>
        <param2>yza</param2>
    </element>
    <element>
        <param1>xyz</param1>
        <param2>yza</param2>
    </element>
</value>

    In this example, constraint NegativeModelParameterConstraint warns when the configuration parameter settings are an invalid structure array:

    <NegativeModelParameterConstraint>    
    <value>
        <element>
            <double>a</double>
            <single>b</single>
       </element>
       <element>
            <double>a</double>
            <single>b</single>
       </element>
    </value>
</NegativeModelParameterConstraint>

  • fixvalue — (Optional) Specifies the setting to use when applying the Model Advisor fix action.

    You can specify the fixvalue using a format in this table.

    TypeFormatExample
    Scalar value 
    <fixvalue>xyz</fixvalue>

    In this example, the fix action tag specifies the new configuration parameter setting as warning.

    <PositiveModelParameterConstraint>
    <value>error</value>
    <fixaction>warning</fixaction>
</PositiveModelParameterConstraint>
    Structure or object 
    <fixvalue>   
    <param1>xyz</param1>
    <param2>yza</param2>
</fixvalue>

    In this example, the fix action tag specifies the new configuration parameter setting for a structure.

    <PositiveModelParameterConstraint>
    <value>
        <double>a</double>
        <single>b</single>
    </value>
    <fixvalue>
        <double>c</double>
        <single>d</single>    
    </fixvalue>
</PositiveModelParameterConstraint>
    Array 
    <fixvalue>
    <element>value</element>
    <element>value</element>
</fixvalue>

    In this example, the fix action tag specifies the new configuration parameter setting for an array.

    <NegativeModelParameterConstraint>
    <value>
        <element>A</element>
        <element>B</element>   
    </value>
    <fixvalue>
        <element>C</element>
        <element>D</element>
    </fixvalue>
</NegativeModelParameterConstraint>
    Structure Array 
    <fixvalue>
    <element>
        <param1>xyz</param1>
        <param2>yza</param2>
    </element>
    <element>
        <param1>xyz</param1>
        <param2>yza</param2>
    </element>
</fixvalue>

    In this example, the fix action tag specifies the new configuration parameter settings for a structure array.

    <NegativeModelParameterConstraint>    
    <value>
        <element>
            <double>a</double>
            <single>b</single>
       </element>
        <element>
            <double>a</double>
            <single>b</single>
        </element>
    </value>
    <fixvalue>
        <element>
            <double>c</double>
            <single>d</single>
        </element>
        <element>
            <double>c</double>
            <single>d</single>
        </element>
    </fixvalue>
</NegativeModelParameterConstraint>

  • dependson - (Optional) Specifies a prerequisite subcheck.

    In this example, dependson specifies that configuration parameter subcheck ID_B must pass before configuration parameter subcheck ID_A runs. 

    <PositiveModelParameterConstraint id="ID_A">
    <dependson>ID_B</value>
</PostitiveModelParameterConstraint>

Data file tagging specifying a configuration parameter

The following tagging specifies a subcheck for configuration parameter SolverType. If the configuration parameter is set to Fixed-Step, the subcheck passes.

<PositiveModelParameterConstraint id="ID_A">    
    <parameter>SolverType</parameter>
    <value>Fixed-step</value>
</PostitiveModelParameterConstraint>

Data file tagging specifying configuration parameter with fix action

The following tagging specifies a subcheck for configuration parameter AlgebraicLoopMsg. If the configuration parameter is set to none or warning, the subcheck passes. If the subcheck does not pass, the check fix action modifies the configuration parameter to error.

<PositiveModelParameterConstraint id="ID_A">    
    <parameter>AlgebraicLoopMsg</parameter>
    <value>none</value>    
    <value>warning</value>
    <fixvalue>error</value>
</PostitiveModelParameterConstraint>

Data file tagging specifying an array type configuration parameter

<PositiveModelParameterConstraint id="A">
    <parameter>ReservedNameArray</parameter>
    <value>
        <element>A</element>
        <element>B</element>
    </value>
    <value>
        <element>A</element>
        <element>C</element>
    </value>
</PositiveModelParameterConstraint>

Data file tagging specifying a structure type configuration parameter with fix action

<PositiveModelParameterConstraint id="A">    
    <parameter>ReplacementTypes</parameter>
    <value>
        <double>a</double>
        <single>b</single>
    </value>
    <value>
        <double>c</double>
        <single>b</single>
    </value>
    <fixvalue>
        <double>a</double>
        <single>b</single>
    </fixvalue>
</PositiveModelParameterConstraint>

Data file tagging specifying configuration parameter with fix action and prerequisite check

The following tagging specifies a subcheck for configuration parameter SolverType. The subcheck for SolverType runs only after the ID_B subcheck passes. If theID_B subcheck does not pass, the subcheck for SolverType does not run. The Model Advisor reports that the prerequisite constraint is not met.

If the SolverType subcheck runs and SolverType is set to Fixed-Step, the SolverType subcheck passes. If the subcheck runs and does not pass, the check fix action modifies the configuration parameter to Fixed-Step.

<PositiveModelParameterConstraint id="ID_A">
    <parameter>SolverType</parameter>
    <value>Fixed-step</value>    
    <fixvalue>Fixed-step</value>
    <dependson>ID_B</value>
</PostitiveModelParameterConstraint>

Data file tagging specifying unwanted configuration parameter

The following tagging specifies a subcheck for configuration parameter SolverType. The subcheck does not pass if the configuration parameter is set to Fixed-Step.

<NegativeModelParameterConstraint id="ID_A">    
    <parameter>SolverType</parameter>
    <value>Fixed-step</value>
</NegativeModelParameterConstraint>

Data file tagging specifying unwanted configuration parameter with fix action

The following tagging specifies a subcheck for configuration parameter SolverType. If the configuration parameter is set to Fixed-Step, the subcheck does not pass. If the subcheck does not pass, the check fix action modifies the configuration parameter to Variable-Step.

<NegativeModelParameterConstraint id="ID_A">    
    <parameter>SolverType</parameter>    
    <value>Fixed-step</value>    
    <fixvalue>Variable-step</value>
</NegativeModelParameterConstraint>

Data file tagging specifying unwanted configuration parameter with fix action and prerequisite check

The following tagging specifies a check for configuration parameter SolverType. The subcheck for SolverType runs only after the ID_B subcheck passes. If theID_B subcheck does not pass, the subcheck for SolverType does not run. The Model Advisor reports that the prerequisite constraint is not met.

If the SolverType subcheck runs and SolverType is set to Fixed-Step, the subcheck does not pass. The check fix action modifies the configuration parameter to Variable-Step.

<NegativeModelParameterConstraint id="ID_A">    
    <parameter>SolverType</parameter>
    <value>Fixed-step</value>
    <fixvalue>Variable-step</value>
    <dependson>ID_B</value>
</NegativeModelParameterConstraint>

See Also

| | |

Related Topics