为模型配置参数创建模型顾问检查

要验证模型的配置参数，可以创建一项配置参数检查。

决定模型要使用的配置参数设置。如果需要，请查看建模规范：

  1. 创建一个包含要检查的配置参数设置的 XML 数据文件。您可以使用 Advisor.authoring.generateConfigurationParameterDataFile 或自己手动创建该文件。

  2. 使用 sl_customization.m 文件注册模型配置参数检查。

  3. 对您的模型运行该检查。

为配置参数检查创建数据文件

此示例说明如何在诊断窗格中创建指定配置参数值的数据文件。当配置参数值与数据文件中定义的值不匹配时，自定义检查会发出警告。

通过输入以下命令打开模型 vdp：

openExample('simulink_general/VanDerPolOscillatorExample')

在模型窗口中右键点击，选择模型配置参数。在诊断窗格中，按如下方式设置配置参数：

  • 代数环设置为无

  • 尽量减少代数环设置为错误

  • 模块优先级违规设置为错误

使用 Advisor.authoring.generateConfigurationParameterDataFile 函数在诊断窗格中创建指定配置参数约束的数据文件。此外，要创建具有修复操作的检查，请将 FixValue 设置为 true。在命令提示符下，键入：

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

在命令行窗口中，选择 ex_DataFile.xml。数据文件将在 MATLAB® 编辑器中打开。

  • 尽量减少代数环 (ArtificialAlgebraicLoopMsg) 配置参数标记将 value 指定为 error，将 fixvalue 指定为 error。当您使用 ex_DataFile.xml 运行配置参数检查时，如果尽量减少代数环设置不是 error，检查将不会通过。检查修复操作将该设置修改为 error。

  • 模块优先级违规 (BlockPriorityViolationMsg) 配置参数标记将 value 指定为 error，将 fixvalue 指定为 error。当您使用 ex_DataFile.xml 运行配置参数检查时，如果模块优先级违规设置不是 error，检查将不会通过。检查修复操作将该设置修改为 error。

在 ex_DataFile.xml 中，编辑代数环 (AlgebraicLoopMsg) 参数标记，以便检查在 value 为 none 时发出警告。由于您要指定的是一个非预期配置参数，因此需要使用 NegativeModelParameterConstraint。此外，要创建一项没有修复操作的子检查，请删除具有 <fixvalue> 标记的行。配置参数的标记如下所示：

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

在 ex_DataFile.xml 中，删除您不想检查的配置参数的标记行。数据文件 ex_DataFile.xml 仅包含代数环、尽量减少代数环和模块优先级违规 的标记行。例如，ex_DataFile.xml 的内容类似于：

<?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>

使用 Advisor.authoring.DataFile.validate 验证数据语法。在命令提示符下，键入：

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

为诊断窗格模型配置参数创建检查

此示例说明如何使用数据文件和 sl_customization.m 文件为诊断窗格模型配置参数创建一项检查。首先，使用 sl_customization.m 文件注册检查。使用 ex_DataFile.xml 时，检查会在以下情况下发出警告：

  • 代数环设置为无

  • 尽量减少代数环未设置为错误

  • 模块优先级违规未设置为错误

检查修复操作将尽量减少代数环和模块优先级违规参数设置修改为错误。

该检查使用在为配置参数检查创建数据文件中创建的 ex_DataFile.xml 数据文件。

关闭模型顾问和您的模型（如果打开）。

使用以下 sl_customization.m 文件指定并注册检查示例:检查模型配置参数。

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');
请注意，模型配置参数设置检查必须使用 setCallbackFcn 类型的 StyleOne。

创建示例:检查模型配置参数。在命令提示符下，输入：

Advisor.Manager.refresh_customizations

通过输入以下命令打开模型 vdp：

openExample('simulink_general/VanDerPolOscillatorExample')

在模型窗口中右键点击，选择模型配置参数。在诊断窗格中，按如下方式设置配置参数：

  • 代数环设置为无

  • 尽量减少代数环设置为警告

  • 模块优先级违规设置为警告

在建模选项卡中，选择模型顾问以打开模型顾问。

在左窗格中，选择演示 示例:检查模型配置参数。在右窗格中，将数据文件设置为 ex_DataFile.xml。

点击运行检查。模型顾问检查发出警告，指出配置参数未设置为 ex_DataFile.xml 中指定的值。对于具有正向约束标记 (PositiveModelParameterConstraint) 的配置参数，从 value 标记中获取的是推荐值。对于具有负向约束标记 (NegativeModelParameterConstraint) 的配置参数，从 value 标记中获取的是不推荐的值。

  • 代数环(AlgebraicLoopMsg) - ex_DataFile.xml 标记没有为 AlgebraicLoopMsg 指定修复操作。仅当设置未设置为无时，子检查才会通过。

  • 尽量减少代数环(ArtificialAlgebraicLoopMsg) - ex_DataFile.xml 标记为 ArtificialAlgebraicLoopMsg 指定了一项具有修复操作的子检查，仅在设置为错误时该子检查才会通过。修复操作将设置修改为错误。

  • 模块优先级违规(BlockPriorityViolationMsg) - ex_DataFile.xml 标记为 BlockPriorityViolationMsg 指定了一项具有修复操作的子检查，当设置为警告时该子检查不会通过。修复操作将设置修改为错误。

在工具条中，点击修复。模型顾问更新模块优先级违规和尽量减少代数环的配置参数。

再次运行演示 > 示例:检查模型配置参数检查。该检查会发出警告，因为代数环设置为无。

在模型顾问窗口的右窗格中，使用 Algebraic loop (AlgebraicLoopMsg) 链接编辑配置参数。将代数环设置为警告或错误。

最后一次运行该检查。检查通过。

用于配置参数检查的数据文件

您可以使用 XML 数据文件来创建配置参数检查。要创建数据文件，您可以使用 Advisor.authoring.generateConfigurationParameterDataFile 或自己手动创建文件。数据文件包含指定检查行为的标记。数据文件中指定的每个模型配置参数均为一项子检查。数据文件的结构如下：

<?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>

<messages> 标记包含：

  • Description -（可选）检查的描述。显示在模型顾问窗口中。

  • PassMessage -（可选）在模型顾问窗口中显示的通过消息。

  • FailMessage -（可选）在模型顾问窗口中显示的失败消息。

  • RecommendedActions -（可选）当检查未通过时，在模型顾问窗口中显示的建议操作。

注意

<messages> 标记是可选的。Advisor.authoring.generateConfigurationParameterDataFile 不生成 <messages> 标记。

在 <checkdata> 标记中，数据文件指定两种类型的约束：

  • PositiveModelParameterConstraint - 指定所需的配置参数设置。

  • NegativeModelParameterConstraint - 指定不需要的配置参数设置。

在两种约束类型的每一种类型的标记中，对于要检查的每个配置参数，数据文件都有以下标记：

  • parameter - 指定要检查的配置参数。标记使用配置参数的命令行名称。例如：

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

  • value - 指定配置参数的设置。您可以指定多个 value 标记。

    使用 PositiveModelParameterConstraint 时，value 指定您所需的配置参数设置。对于 NegativeModelParameterConstraint，value 指定您不需要的配置参数设置。

    您可以使用下表中的一种格式指定 value。

    类型格式示例
    标量值 
    <value>xyz</value>

    在本示例中，当配置参数的配置参数设置不是 error 或 none 时，约束 NegativeModelParameterConstraint 会发出警告。

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

    结构体或对象 
    <value>
    <param1>xyz</param1>
    <param2>yza</param2>
</value>

    在本示例中，当配置参数设置不是有效结构体时，约束 PositiveModelParameterConstraint 会发出警告：

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

    数组 
    <value>
    <element>value</element>
    <element>value</element>
</value>

    在本示例中，当配置参数设置是无效数组时，约束 NegativeModelParameterConstraint 会发出警告：

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

    结构体数组 
    <value>
    <element>
        <param1>xyz</param1>
        <param2>yza</param2>
    </element>
    <element>
        <param1>xyz</param1>
        <param2>yza</param2>
    </element>
</value>

    在本示例中，当配置参数设置是无效的结构体数组时，约束 NegativeModelParameterConstraint 会发出警告：

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

  • fixvalue -（可选）指定应用模型顾问修复操作时要使用的设置。

    您可以使用下表中的一种格式指定 fixvalue。

    类型格式示例
    标量值 
    <fixvalue>xyz</fixvalue>

    在本示例中，修复操作标记将新配置参数设置指定为 warning。

    <PositiveModelParameterConstraint>
    <value>error</value>
    <fixaction>warning</fixaction>
</PositiveModelParameterConstraint>
    结构体或对象 
    <fixvalue>   
    <param1>xyz</param1>
    <param2>yza</param2>
</fixvalue>

    在此示例中，修复操作标记为结构体指定新配置参数设置。

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

    在本示例中，修复操作标记为数组指定新配置参数设置。

    <NegativeModelParameterConstraint>
    <value>
        <element>A</element>
        <element>B</element>   
    </value>
    <fixvalue>
        <element>C</element>
        <element>D</element>
    </fixvalue>
</NegativeModelParameterConstraint>
    结构体数组 
    <fixvalue>
    <element>
        <param1>xyz</param1>
        <param2>yza</param2>
    </element>
    <element>
        <param1>xyz</param1>
        <param2>yza</param2>
    </element>
</fixvalue>

    在此示例中，修复操作标记为结构体数组指定新配置参数设置。

    <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 -（可选）指定前提条件子检查。

    在本示例中，dependson 指定在运行配置参数子检查 ID_A 之前，必须先通过配置参数子检查 ID_B。 

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

指定配置参数的数据文件标记

以下标记为配置参数 SolverType 指定一项子检查。如果配置参数设置为 Fixed-Step，则子检查通过。

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

指定配置参数且具有修复操作的数据文件标记

以下标记为配置参数 AlgebraicLoopMsg 指定一项子检查。如果配置参数设置为 none 或 warning，则子检查通过。如果子检查未通过，检查修复操作会将配置参数修改为 error。

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

指定数组类型配置参数的数据文件标记

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

指定结构体类型配置参数且具有修复操作的数据文件标记

<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>

指定配置参数且具有修复操作和前提条件检查的数据文件标记

以下标记为配置参数 SolverType 指定一项子检查。SolverType 的子检查仅在 ID_B 子检查通过后运行。如果 ID_B 子检查未通过，SolverType 的子检查将不会运行。模型顾问报告会指出前提条件约束未得到满足。

如果运行 SolverType 的子检查且 SolverType 设置为 Fixed-Step，则 SolverType 的子检查通过。如果运行子检查且未通过，则检查修复操作会将配置参数修改为 Fixed-Step。

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

指定不需要的配置参数的数据文件标记

以下标记为配置参数 SolverType 指定一项子检查。如果配置参数设置为 Fixed-Step，则子检查不会通过。

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

指定不需要的配置参数且具有修复操作的数据文件标记

以下标记为配置参数 SolverType 指定一项子检查。如果配置参数设置为 Fixed-Step，则子检查不会通过。如果子检查未通过，检查修复操作会将配置参数修改为 Variable-Step。

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

指定不需要的配置参数且具有修复操作和前提条件检查的数据文件标记

以下标记指定对配置参数 SolverType 的检查。SolverType 的子检查仅在 ID_B 子检查通过后运行。如果 ID_B 子检查未通过，SolverType 的子检查将不会运行。模型顾问报告会指出前提条件约束未得到满足。

如果运行 SolverType 的子检查且 SolverType 设置为 Fixed-Step，则该子检查不会通过。检查修复操作将配置参数修改为 Variable-Step。

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

另请参阅

| | |

主题