Define Custom Model Advisor Checks

You can create your own conditions and model configuration settings for the Model Advisor to review by defining custom checks. You can create custom checks that run during edit-time and in the Model Advisor or only in the Model Advisor.

Custom edit-time checks help you identify issues earlier in the model design process, but they look only at blocks and signals at the same level of the model or subsystem that a user is editing. However, these checks do aggregate over the levels of a model hierarchy and report issues in the Model Advisor. If your check must check for impacted blocks at other levels of the model, create a custom check that runs only in the Model Advisor. For example, if your check must check for mismatched From and Goto blocks across a model hierarchy, define this check to run only in the Model Advisor.

These steps show the process for creating checks that run during edit-time or only in the Model Advisor.

1. Create sl_customization Function

2. Register Custom Checks

3. Create Check Definition Function

   1. Create an Instance of the ModelAdvisor.Check Class

   2. Define your custom check by following the steps in either Define Custom Model Advisor Checks or Define Custom Edit-Time Checks.

   3. Define Check Input Parameters

   4. Publish Custom Check

Create sl_customization Function

To define a custom check, begin by creating an sl_customization.m file on the MATLAB path. In the sl_customization.m file, create an sl_customization function. The sl_customization function accepts one argument, a customization manager object:

function sl_customization(cm)

Tip

• You can have more than one sl_customization.m file on your MATLAB path.

• Do not place an sl_customization.m file that customizes Model Advisor checks and folders in your root MATLAB^® folder or its subfolders, except for the matlabroot/work folder. Otherwise, the Model Advisor ignores the customizations that the file specifies.

Register Custom Checks

To register custom checks, use the addModelAdvisorCheckFcn method, which is part of the customization manager object that you input to the sl_customization function. This code shows a sample sl_customization.m function:

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

% -----------------------------
% defines Model Advisor Checks
% -----------------------------
function defineModelAdvisorChecks
defineDetailStyleCheck;
defineConfigurationParameterCheck;
defineNewBlockConstraintCheck;
defineEditTimeChecks;

The addModelAdvisorCheckFcn method registers the checks to the By Product folder of the Model Advisor. The defineModelAdvisorChecks argument is a handle to the function that contains calls to the functions that define the custom checks. For each custom Model Advisor check that you create, you should create a check definition function. You can create one check definition function for your edit-time checks because each edit-time check contains its own class definition. For more information on the functions that define the custom checks, refer Create and Deploy Model Advisor Custom Configuration.

Create Check Definition Function

The check definition function defines the actions that the Model Advisor takes when you run the check. These sections describe the key components of the check definition function for custom edit-time checks and checks that run only in the Model Advisor.

Create an Instance of the ModelAdvisor.Check Class

For each custom check, create one instance of the ModelAdvisor.Check class. Use the ModelAdvisor.Check properties and methods to define the check user interface and actions. This table describes some key check components.

Contents	Description
Check ID (required)	Uniquely identifies the check. The Model Advisor uses this ID to access the check.
(Custom Model Advisor check only) Handle to the check callback function (required)	Function that specifies the contents of a check.
(Custom Model Advisor check only) Handle to action callback function (optional)	Adds a fixing action.
(Custom Edit-time check only) Handle to class (required)	Derived class that defines the actions for the edit-time check. Optionally, this class can also define a fix for the edit-time check.
Check name (recommended)	Specifies a name for the check in the Model Advisor.
Model compiling (optional)	Specifies whether the model is compiled for check analysis. The PostCompileForCodegen value of the CallbackContext property is not supported for edit-time checks.
Input parameters (optional)	Adds input parameters that request input from the user. The Model Advisor uses the input to perform the check.

Warning

The properties of ModelAdvisor.Check are generally case-insensitive, however, inheriting the ModelAdvisor.Check class to create custom checks is not a supported workflow, as the check properties of the inherited class become case-sensitive.

Define Custom Model Advisor Checks

For a custom check that only appears in the Model Advisor, the check definition function contains a check callback function that specifies the actions that you want the Model Advisor to perform on a model or subsystem. Define the check callback function and pass a handle to it to the setCallbackFcn method. The Model Advisor executes the callback function when you run the check. Callback functions provide one or more return arguments that display the results after executing the check. The Model Advisor executes the callback function when you run the check.

If you are specifying a custom check fix, the check definition function should also contain an action callback function. In the check definition function, create an instance of the ModelAdvisor.Action class. Define the action callback function and pass a handle to it to the setCallbackFcn method. In the Model Advisor, the check user clicks Fix to apply the custom fix to their model.

Callback and action callback functions provide one or more return arguments for displaying the results after executing the check. See Create the Check Callback Definition Function and Create the Action Callback Definition Function.

To use default formatting for Model Advisor results, specify the callback function type as DetailStyle in the setCallbackFcn method. If the default formatting does not meet your needs, use either the ModelAdvisor.FormatTemplate class or these other Model Advisor formatting classes:

Class	Description
ModelAdvisor.Text	Create a Model Advisor text output.
ModelAdvisor.List	Create a list.
ModelAdvisor.Table	Create a table.
ModelAdvisor.Paragraph	Create and format a paragraph.
ModelAdvisor.LineBreak	Insert a line break.
ModelAdvisor.Image	Include an image in the Model Advisor output.

Define Custom Edit-Time Checks

To create a custom edit-time check, create a MATLAB class that derives from the ModelAdvisor.EdittimeCheck class. In the check definition function, specify this class as the value of the ModelAdvisor.Check CallbackHandle property. Inside the derived class, define these methods:

• Define a method that specifies the check ID and the ModelAdivsor.EdittimeCheck.TraversalType properties of the check. The TraversalType property specifies how the Model Advisor runs the check.

• Define a blockDiscovered method that looks for blocks that violate your edit-time algorithm.

• If the violation is on a block, highlight the block during edit-time by creating a ModelAdvisor.ResultDetail violation object with the Type property set to the default value of SID. If the violation is on a signal, highlight the signal by creating a violation object with the Type property set to Signal.

• If you specify a TraversalType property of edittimecheck.TraversalTypes.ACTIVEGRAPH, define a finishedTraversal method that specifies what the edit-time check does with the data the check collects as part of the blockDiscovered method.

• Optionally, define a fix method for edit-time check violations.

For an example, see Define Edit-Time Checks to Comply with Conditions That You Specify with the Model Advisor.

To help prevent custom edit-time checks from negatively impacting performance as you edit your model, the Model Advisor automatically disables custom edit-time checks if, in the current MATLAB session, the check takes longer than 500 milliseconds to execute in at least three different Simulink^® models.

If the Model Advisor disables a custom edit-time check, you will see a warning on the Simulink canvas. You can re-enable the edit-time check by either:

• Clicking the hyperlink text in the warning.

• Passing the check identifier, checkID, to the function edittime.enableCheck: edittime.enableCheck(checkID).

To prevent a custom edit-time check from being disabled, author the check so that the check executes in less than 500 milliseconds on your models.

Define Check Input Parameters

You can request input before running the check by using input parameters. Define input parameters by using the ModelAdvisor.InputParameter class. You must include input parameter definitions inside a custom check definition function. You must define one instance of this class for each input parameter that you want to add to a custom check.

Specify the layout of input parameters in the Model Advisor by using these methods.

Purpose	Method
Specifies the size of the input parameter grid	setInputParametersLayoutGrid
Specifies the number of rows the parameter occupies in the input parameter layout grid.	setRowSpan
Specifies the number of columns the parameter occupies in the input parameter layout grid.	setColSpan

The Model Advisor displays input parameters in the Input Parameters box.

Display and Enable Check

You can specify how a custom check appears in the Model Advisor. You can define when to display a check, or whether a user can select or clear a check using the Visible, Enable, and Value properties of the ModelAdvisor.Check class. These properties interact as follows:

• If the Visible property is false, the check or task is not displayed in the Model Advisor and the Enable and Value properties are ignored.

• If the Visible property is true and the Enable property is false:

  • The check is displayed in the Model Advisor.

  • The initial status of the check is Value.

  • The check box appears dimmed.

• If the Visible property is true and the Enabled property is true, the check or task is displayed in the Model Advisor and the check box is active.

Registering Custom Check

To register the customer checks using the following command:

Advisor.Manager.refresh_customizations

Publish Custom Check

Create a folder for custom checks in the By Product folder by using the publish method. The new folder with the published custom authored checks are available in the Model Advisor root and they appear in the Model Advisor tree. Then, use the Model Advisor Configuration Editor to customize the folders within the Model Advisor tree and create a custom configuration. For more information, see Use Model Advisor Configuration Editor to Customize Model Advisor.

You can also use the Model Advisor Configuration API Advisor.Config to programmatically create a custom configuration that includes the published custom checks available in the Model Advisor root. Using the addFolder function, you can create custom folders for the custom configuration and add the custom checks in it by using the addCheck function. For more information, see Customize Model Advisor Configuration Programmatically.