Create and Deploy a Model Advisor Custom Configuration

Open Live Script

To check that a model meets your company's standards and modeling guidelines, you can customize the Model Advisor. This example shows you how to add custom checks to the Model Advisor and remove shipping checks that you do not require. You can save a custom configuration and deploy it to others in your development group. Deploying a custom configuration allows your development group to review models using the same set of checks.

Define Custom Checks

This example defines these three types of custom checks:

  • A pass/fail check that groups results by blocks and subsystems and provides a fix action.

  • A check that verifies model configuration parameter settings.

  • A check that specifies a constraint for a block parameter setting and provides a fix action.

In this example, you will add the three checks to the Model Advisor and remove all shipping checks.

1. Set your current folder to a writeable directory.

2. Copy the script prepare_cust_chk_code to your current folder and run the script. The script copies the files necessary for this example to your current folder.

copyfile(fullfile(matlabroot,'examples','slcheck','main','prepare_cust_chk_code.m'),...
    'prepare_cust_chk_code.m','f');
run('prepare_cust_chk_code.m');

3. One of the files, sl_customization.m, includes an sl_customization function that defines custom checks. Open and inspect the sl_customization.m file.

function sl_customization(cm)
% SL_CUSTOMIZATION - Model Advisor customization demonstration.

% Copyright 2019 The MathWorks, Inc.

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

% -----------------------------
% defines Model Advisor Checks
% -----------------------------
function defineModelAdvisorChecks
defineDetailStyleCheck;
defineConfigurationParameterCheck;
defineBlockConstraintCheck;

The sl_customization function accepts a customization manager object. The customization manager object includes the addModelAdvisorCheckFcn method for registering custom checks. The input to this method is a handle to a function (defineModelAdvisorChecks). This function contains calls to the three check definition functions that correspond to the three custom checks.

Pass/Fail Check with Fix Action

The defineDetailStyleCheck.m file contains the defineDetailStyleCheck definition function, which defines a check that lists blocks whose names are not displayed below the blocks. This check provides a fix that moves those names below the blocks. The name of this check is Check whether block names appear below blocks. Open and inspect the defineDetailStyleCheck.m file.

function defineDetailStyleCheck

mdladvRoot = ModelAdvisor.Root;

% Create ModelAdvisor.Check object and set properties.
rec = ModelAdvisor.Check('com.mathworks.sample.detailStyle');
rec.Title = 'Check whether block names appear below blocks';
rec.TitleTips = 'Check position of block names';
rec.setCallbackFcn(@DetailStyleCallback,'None','DetailStyle');
% Create ModelAdvisor.Action object for setting fix operation.
myAction = ModelAdvisor.Action;
myAction.setCallbackFcn(@ActionCB);
myAction.Name='Make block names appear below blocks';
myAction.Description='Click the button to place block names below blocks';
rec.setAction(myAction);
mdladvRoot.publish(rec, 'Demo'); % publish check into Demo group.

end

% -----------------------------
% This callback function uses the DetailStyle CallbackStyle type. 
% -----------------------------
function DetailStyleCallback(system, CheckObj)
mdladvObj = Simulink.ModelAdvisor.getModelAdvisor(system); % get object

% Find all blocks whose name does not appear below blocks
violationBlks = find_system(system, 'Type','block',...
    'NamePlacement','alternate',...
    'ShowName', 'on');
if isempty(violationBlks)
    ElementResults = ModelAdvisor.ResultDetail;
    ElementResults.IsInformer = true;
    ElementResults.Description = 'Identify blocks where the name is not displayed below the block.';
    ElementResults.Status = 'All blocks have names displayed below the block.';
    mdladvObj.setCheckResultStatus(true);
else
    ElementResults(1,numel(violationBlks))=ModelAdvisor.ResultDetail;
    for i=1:numel(ElementResults)
        ElementResults(i).setData(violationBlks{i});
        ElementResults(i).Description = 'Identify blocks where the name is not displayed below the block.';
        ElementResults(i).Status = 'The following blocks have names that do not display below the blocks:';
        ElementResults(i).RecAction =  'Change the location such that the block name is below the block.';
    end
    mdladvObj.setCheckResultStatus(false);
    mdladvObj.setActionEnable(true);
end
CheckObj.setResultDetails(ElementResults);
end

% -----------------------------
% This action callback function changes the location of block names. 
% -----------------------------
function result = ActionCB(taskobj)
mdladvObj = taskobj.MAObj;
checkObj = taskobj.Check;
resultDetailObjs = checkObj.ResultDetails;
for i=1:numel(resultDetailObjs)
    % take some action for each of them
    block=Simulink.ID.getHandle(resultDetailObjs(i).Data);
    set_param(block,'NamePlacement','normal');
end

result = ModelAdvisor.Text('Changed the location such that the block name is below the block.');
mdladvObj.setActionEnable(false);
end

This check uses the setCallbackFcn type of DetailStyle. Applying this style produces default formatting, so that you do not have to use the ModelAdvisor.FormatTemplate or the other Model Advisor formatting APIs to format the results that appear in the Model Advisor. For more information on how to create this type of check definition function, see Fix a Model to Comply with Conditions that You Specify With the Model Advisor.

Model Configuration Parameter Settings Check

The defineConfigurationParameterCheck.m file contains the defineConfigurationParameterCheck check definition function, which defines a check that identifies model configuration parameter settings that might impact MISRA C:2012 compliant code generation. The name of this check is Check model configuration parameters.

This check type requires a supporting XML data file that contains the model configuration parameter settings that you want to check. This file must be on the MATLAB path. For this example, that file is configurationParameterDataFile.xml. For more information on how to create this check type, see Create Model Advisor Check for Model Configuration Parameters.

Open and inspect the defineConfigurationParameterCheck.m file.

function defineConfigurationParameterCheck

% Create ModelAdvisor.Check object and set properties.
rec = ModelAdvisor.Check('com.mathworks.sample.configurationParameter');
rec.Title = 'Check model configuration parameters';
rec.setCallbackFcn(@(system)(Advisor.authoring.CustomCheck.checkCallback...
    (system)), 'None', 'StyleOne');
rec.TitleTips = 'Identify configuration parameters that might impact MISRA C:2012 compliant code generation.';

% --- data file input parameters
rec.setInputParametersLayoutGrid([1 1]);
inputParam1 = ModelAdvisor.InputParameter;
inputParam1.Name = 'Data File';
inputParam1.Value = 'configurationParameterDataFile.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);

% publish check into Demo group.
mdladvRoot = ModelAdvisor.Root;
mdladvRoot.publish(rec, 'Demo'); 

end

Block Parameter Constraint Check

The defineBlockConstraintCheck.m file contains the defineBlockConstraintCheck check definition function, which defines a check that identifies Logical Operator blocks that do not have a rectangular shape. The name of this check is Check icon shape of Logical Operator blocks.

This check type supports edit-time checking and requires a supporting XML file that contains the block constraint information. This XML file must be on the MATLAB path. For this example, that file name is blockConstraintDataFile.xml. For more information on this check type, see Define Model Advisor Checks for Supported or Unsupported Blocks and Parameters.

Open and inspect the defineBlockConstraintCheck.m file.

function defineBlockConstraintCheck

rec = Advisor.authoring.createBlockConstraintCheck('com.mathworks.sample.blockConstraint');
rec.Title = 'Check icon shape of Logical Operator blocks';
rec.setCallbackFcn(@(system)(Advisor.authoring.CustomCheck.checkCallback...
    (system)), 'None', 'StyleOne');
rec.TitleTips = 'Checks icon shape of Logical Operator blocks. Icon shape of Logical Operator should be rectangular.';

% --- data file input parameters
rec.setInputParametersLayoutGrid([1 1]);
inputParam1 = ModelAdvisor.InputParameter;
inputParam1.Name = 'Data File';
inputParam1.Value = 'blockConstraintDataFile.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});
rec.SupportExclusion = false;
rec.SupportLibrary = true;

% publish check into Demo group.
mdladvRoot = ModelAdvisor.Root;
mdladvRoot.publish(rec, 'Demo'); 

end

View Custom Checks in the Model Advisor

1. In order for your custom checks to be visible in the Model Advisor, you must refresh the Model Advisor check information cache. At the MATLAB command prompt, type this command:

Advisor.Manager.refresh_customizations();

2. Open the example model.

open_system('AdvisorCustomizationExample.slx');

3. On the Modeling tab, open the Model Advisor. You can also open the Model Advisor by typing this command at the MATLAB command prompt:

modeladvisor('AdvisorCustomizationExample.slx');
Updating Model Advisor cache...
Model Advisor cache updated. For new customizations, to update the cache, use the Advisor.Manager.refresh_customizations method.

4. Observe the custom checks in the By Product > Demo folder.

In the check definition functions, the publish command adds the checks to the By Product > Demo folder. Note, if you already have a default configuration set, the checks do not appear in the Model Advisor. Restore the default shipping configuration by selecting Settings > Restore Default Configuration.

Notice that the Check whether block names appear below blocks and the Check model configuration parameters checks contain an Action box with the option of fixing any check violations. In your custom check definition file, you supply the fix as part of the action callback function. For more information on how to define custom checks, see Define Your Own Custom Model Advisor Checks.

On the model canvas, observe that the Unit Delay and Logical Operator blocks are highlighted in yellow because edit-time checking is on. These blocks contain check violations. Edit-time checking allows you to interactively check and fix your model for compliance issues.

To fix these violations, hover over a highlighted block and click the yellow icon. A diagnostic box with a Fix button opens.

To turn edit-time checking on or off, on the Modeling tab, select Model Advisor > Edit-Time Checks.

Specify and Deploy a Model Advisor Custom Configuration

To specify which checks to include in the Model Advisor and which checks to use for edit-time checking, use the Model Advisor Configuration Editor.

1. To open the Configuration Editor, on the Modeling tab, select Model Advisor > Model Advisor Configuration Editor.

2. To add or remove checks and folders, select from the options in the Edit section of the Model Advisor Configuration Editor.

3. To save a configuration, select Save. A window opens and prompts you to save the configuration as a .json file. For this example, you do not have to save the configuration, as the corresponding demoConfiguration.json file ships with this example. You previously copied this file to your working folder.

4. Close the model and the Model Advisor Configuration Editor.

bdclose;

When you save a configuration, you get a prompt asking you whether you want to save that configuration as the default configuration. Setting a default configuration allows the Model Advisor to use that configuration every time you open the Model Advisor. For more information, see Use the Model Advisor Configuration Editor to Customize the Model Advisor.

Load and Run a Model Advisor Custom Configuration

1. Open the example model.

open_system('AdvisorCustomizationExample.slx');

2. Open the Model Advisor. Load the custom configuration by selecting Settings > Load Configuration. In the Open dialog box, navigate to and select the demoConfiguration.json file. Or enter this command at the MATLAB command prompt:

modeladvisor('AdvisorCustomizationExample.slx', 'configuration',...
    'demoConfiguration.json');
Model Advisor is removing the existing report.

3. A Warning dialog box opens. Click Remove existing report and continue.

The Model Advisor contains only the By Product > Demo folder with the three custom checks.

3. Click the Demo folder and click Run Selected Checks.

4. Click the Check whether block names appear below blocks check. This check contains warnings. To apply a fix and resolve the warnings, on the right pane, click the Make block names appear below blocks button.

5. Click the Check model configuration parameters check. This check contains warnings. To apply a fix and resolve the warnings, click the Modify Settings button.

6. Click the Check icon shape of Logical Operator blocks check. This check contains a warning but no automatic fix. To apply a fix, follow the recommended action.

7. Close the model and the Model Advisor. 

bdclose;

8. Remove the files from your working directory. Refresh the Model Advisor check information cache by typing this command at the command type:

Advisor.Manager.refresh_customizations

Programmatically Run a Model Advisor Custom Configuration and View Results

You can programmatically run a Model Advisor configuration and then open the results in the Model Advisor.

1. Call the ModelAdvisor.run function.

SysResultObjArray = ModelAdvisor.run({'AdvisorCustomizationExample'},...
'Configuration','demoConfiguration.json');

2. View the results in the Model Advisor:

viewReport(SysResultObjArray{1},'MA')

3. Click Continue in the dialog box. You can now apply fixes and resolve warnings as you did towards the end of the previous section.

4. Close the model and the Model Advisor.

bdclose;

5. Remove the files from your working directory. Refresh the Model Advisor check information cache by typingthis command at the command type:

Advisor.Manager.refresh_customizations

Simulink Check Documentation

Support