finishedTraversal

Class: ModelAdvisor.EdittimeCheck
Namespace: ModelAdvisor

Specify edit-time check algorithm to run after blockDiscovered method

Since R2022a

Syntax

violation = finishedTraversal(obj)


Description

violation = finishedTraversal(obj) is for specifying an algorithm that gets called after the blockDiscovered method traverses the blocks at the same level of the model or subsystem that the user is editing. Use this method when you specify a value of edittimecheck.TraversalTypes.ACTIVEGRAPH for the TraversalType property for the edit-time check object, obj. The method returns the blocks that violate your edit-time check algorithm, violation.

Use the finishedTraversal method for specifying what the edit-time check should do with the data it collects as part of the blockDiscovered method. For example, suppose you define an edit-time check that flags subsystems with more than 20 blocks. In this scenario, the blockDiscovered method traverses each block in the subsystem and counts the number of blocks. The finishedTraversal method is then called and if the subsystem contains more than 20 blocks, it creates an edit-time check violation.

Input Arguments

obj — Edit-time check object

object of a class that derives from the ModelAdvisor.EdittimeCheck class

Edit-time check object, specified as an object of a class that derives from the ModelAdvisor.EdittimeCheck class.

Output Arguments

violation — Model Advisor result detail object

ModelAdvisor.ResultDetail | array of ModelAdvisor.ResultDetail objects

Blocks that violate the edit-time check, returned as a ModelAdvisor.ResultDetail object or an array of ModelAdvisor.ResultDetail objects.

Attributes

Access

protected

To learn about attributes of methods, see Method Attributes.

Examples

Create Custom Edit-time Check to Check the Position of a Trigger Block

Create a custom edit-time check that checks the position of a Trigger block within a subsystem. This check requires the finishedTraversal method because it must specify violation information after it checks the position of blocks in a subsystem.

Obtain a model to try out the Model Advisor check.

openExample('AdvisorCustomizationExample')

Save the model to your working folder. Close the model.

To register the custom edit-time check, create an sl_customization function. The sl_customization function accepts one argument, a customization manager object. To register the custom check, use the addModelAdvisorCheckFcn method. The input to this method is a handle to the check definition function. For this example, defineCheck is the check definition function. Create the sl_customization function and save it to your working folder.

function sl_customization(cm)
cm.addModelAdvisorCheckFcn(@defineCheck);

Create the check definition function. Inside the function, create a ModelAdvisor.Check object and specify the Check ID as an input argument. Then, specify the ModelAdvisor.Check Title and CallbackHandle properties. The CallbackHandle property is the name of the class that you create to define the edit-time check. For this example, MyEditTimeChecks is the package name and TriggerBlockPosition is the class name. Then, publish the check to a new folder in the Model Advisor. For this example, the folder name is DEMO: Edit-time Checks. For this example, create a defineCheck function and include the code below in it. Save the defineCheck function to your working folder.

function defineCheck
rec= ModelAdvisor.Check("advisor.edittimecheck.TriggerBlock");
rec.Title = 'Check that Trigger block position is higher than other blocks';
rec.CallbackHandle = 'MyEditTimeChecks.TriggerBlockPosition';
mdladvRoot.publish(rec,'DEMO: Edit Time Checks');

Create a class that derives from the ModelAdvisor.EdittimeCheck abstract base class. For this example, create a class file named TriggerBlockPosition.m. Copy the code below into the TriggerBlockPosition.m file. Then, create a folder named +MyEditTimeChecks and save the TriggerBlockPosition.m file in that folder. The class must be in a folder that has the same name as the package name.

The TriggerBlockPosition class defines three methods: TriggerBlockPosition, blockDiscovered, and finishedTraversal. The TriggerBlockPosition method sets the CheckId and TraversalType properties. This check has a traversal type of edittimecheck.TraversalTypes.ACTIVEGRAPH because it must check other blocks in the same subsystem as the Trigger block. The blockDiscovered method checks the position of Trigger blocks within subsystems. The finishedTraversal method checks whether the position of these Trigger blocks are higher than other blocks in a subsystem.

classdef TriggerBlockPosition < ModelAdvisor.EdittimeCheck
    properties
        TriggerBlock = [];
        position = [];
    end
 
 methods
        % Set Check ID and traversal type.
        function obj=TriggerBlockPosition(checkId)
            obj=[e-mail](checkId);
            obj.traversalType = edittimecheck.TraversalTypes.ACTIVEGRAPH;
        end
 
        function violation = blockDiscovered(obj, blk)
            violation = [];
            if strcmp(get_param(blk,'BlockType'),'TriggerPort')
                obj.TriggerBlock = blk;
            else
                h = get_param(blk,'Position');
                obj.position = [obj.position, h(2)];
            end
        end
 
        function violation = finishedTraversal(obj)
            violation = [];
            if isempty(obj.TriggerBlock) 
                return;
            end
            triggerPosition = get_param(obj.TriggerBlock,'Position');
            if min(obj.position) < triggerPosition(2)
                violation = ModelAdvisor.ResultDetail;
                ModelAdvisor.ResultDetail.setData(violation,'SID',...
                Simulink.ID.getSID(obj.TriggerBlock)); 
                violation.CheckID = obj.checkId;
                violation.title = 'Trigger Block Position';
                violation.Description = 'Trigger Block should be top block in subsystem'; 
                violation.ViolationType = 'Warning'; 
            end
            obj.TriggerBlock = [];
            obj.position =[]; 
        end 
    end
end

Refresh the Model Advisor to update the cache with the new check on the path.

Advisor.Manager.refresh_customizations

Open the AdvisorCustomizationExample model.

Open the Model Advisor Configuration Editor by clicking the Modeling tab and selecting Model Advisor > Configuration Editor or by entering this command at the command prompt:

Simulink.ModelAdvisor.openConfigUI;

Create a custom configuration consisting of the custom edit-time check. Save the configuration as my_config2.json. Close the Model Advisor Configuration Editor. Set the custom configuration to the my_config2.json file.

ModelAdvisor.setModelConfiguration('AdvisorCustomizationExample', ''my_config2.json');

Turn on edit-time checking by clicking the Modeling tab and selecting Model Advisor > Edit Time checks. After the Configuration Parameters dialog box opens, select the Edit-Time Checks parameter. Alternatively, you can enter this command at the command prompt:

edittime.setAdvisorChecking('AdvisorCustomizationExample','on');

To view the edit-time warnings, click the blocks highlighted in yellow.

In the Amplifier subsystem, the Trigger block does not produce an edit-time warning because it is the top-most block in the subsystem. If you move the Trigger block below another block, the produces an edit-time warning.

Version History

Introduced in R2022a