ModelAdvisor.run

Use Model Advisor to run checks on systems

Syntax

ModelAdvisor.run(Systems,CheckIDList)

ModelAdvisor.run(Systems,'Configuration', fileName)

ModelAdvisor.run(Systems,{{CheckID,'InputParam',{paramName,paramValue}}})

ModelAdvisor.run(Systems,{{CheckID1,'InputParam',{paramName1,paramValue1,...,paramNameN,paramValueN}},...,{CheckIDN,'InputParam',{paramName1,paramValue1,...,paramNameN,paramValueN}}})

Results = ModelAdvisor.run(___,Name,Value)

Description

ModelAdvisor.run(Systems,CheckIDList) runs the Model Advisor on the models or subsystems specified by Systems for the list of check IDs specified by CheckIDList.

ModelAdvisor.run(Systems,'Configuration', fileName) runs the Model Advisor for the list of checks specified by the Model Advisor configuration file fileName.

ModelAdvisor.run(Systems,{{CheckID,'InputParam',{paramName,paramValue}}}) runs the Model Advisor for the check ID specified by CheckID with the input parameter setting specified by the input parameter name paramName and the input parameter value paramValue.

ModelAdvisor.run(Systems,{{CheckID1,'InputParam',{paramName1,paramValue1,...,paramNameN,paramValueN}},...,{CheckIDN,'InputParam',{paramName1,paramValue1,...,paramNameN,paramValueN}}}) runs the Model Advisor for one or more check IDs with the input parameter settings specified using 'InputParam'.

The check IDs are specified by CheckID1 through CheckIDN. For each check ID, you can specify the input parameters for the check by using 'InputParam' with the parameter names, paramName1 through paramNameN, and parameter values, paramValue1 through paramValueN.

For example, to specify input parameters for the check Check trigger signal names, you would use: {'mathworks.jmaab.db_0032','InputParam',{'Follow links','off','Look under masks','all'}}.

Results = ModelAdvisor.run(___,Name,Value) specifies the properties of the Model Advisor analysis using one or more Name,Value pair arguments and returns the results in Results. Use Results to view the properties of the Model Advisor run. Use this option with one of the previous syntaxes.

Examples

Use Model Advisor to Run List of Checks

Create a list of the check IDs for the checks Check model diagnostic parameters and Check for unconnected objects.

checkIDs = {'mathworks.maab.jc_0021',...
'mathworks.iec61508.UnconnectedObjects'};

Open the example model sldemo_auto_climatecontrol.

openExample('sldemo_auto_climatecontrol')

Create a list of the subsystems sldemo_auto_climatecontrol/Heater Control and sldemo_auto_climatecontrol/AC Control.

systems = {'sldemo_auto_climatecontrol/Heater Control',...
    'sldemo_auto_climatecontrol/AC Control'};

Use Model Advisor to run the checks on the subsystems.

results = ModelAdvisor.run(systems,checkIDs);

For more information on Model Advisor checks, see Model Advisor Checks Documentation. For details on how to find check IDs, see Find Model Advisor Check IDs.

Use Model Advisor to Run Subchecks

Create a list of checks that specify the input parameter values, then use Model Advisor to run the checks.

Open the model vdp by entering:

openExample('vdp')

Create a list of the input parameters used by the checks Check signal line connections and Check trigger signal names.

To find the input parameters for the checks, create a Model Advisor object for the model and use getInputParameters. The check ID for the check Check signal line connections is 'mathworks.jmaab.db_0032' and the check ID for the check Check trigger signal names is 'mathworks.jmaab.jc_0281'.

ma = Simulink.ModelAdvisor.getModelAdvisor('vdp');

db_0032_parameters = getInputParameters(ma, 'mathworks.jmaab.db_0032');
jc_0281_parameters = getInputParameters(ma, 'mathworks.jmaab.jc_0281');

For the check 'mathworks.jmaab.db_0032', db_0032_parameters{6} contains the InputParameter properties for the input parameter Follow links. Save the input parameter name to the variable followLinks.

followLinks = db_0032_parameters{6}.Name;

For 'mathworks.jmaab.db_0032', set the input parameter Follow links to 'off'. When Follow links is 'off', Model Advisor does not analyze the content of library-linked blocks.

check1 = {'mathworks.jmaab.db_0032',...
'InputParam',{followLinks,'off'}};

For the check 'mathworks.jmaab.jc_0281', jc_0281_parameters{1} contains the InputParameter properties for the input parameter jc_0281_a and jc_0281_parameters{2} contains the InputParameter properties for the input parameter jc_0281_b. jc_0281_a and jc_0281_b contain subchecks for 'mathworks.jmaab.jc_0281'. Save the input parameter names to the variables subCheckA and subCheckB.

subCheckA = jc_0281_parameters{1}.Name;
subCheckB = jc_0281_parameters{2}.Name;

Select the subcheck 'jc_0281_a2' and disable the 'jc_0281_b' subchecks. The input parameter value 2 selects the second subcheck of 'jc_0281_a'. The input parameter value 0 disables 'jc_0281_b' subchecks. For more information on 'mathworks.jmaab.jc_0281' and its subchecks, see Check trigger signal names.

check2 = {'mathworks.jmaab.jc_0281',...
'InputParam',{subCheckA, 2, subCheckB, 0}};

Create the list of checks.

listOfChecks = {check1, check2};

Use Model Advisor to run the specified checks on the system vdp.

results = ModelAdvisor.run('vdp', listOfChecks)

For more information on Model Advisor checks and subchecks, see Model Advisor Checks Documentation. For details on how to find check IDs, see Find Model Advisor Check IDs.

Use Model Advisor to Run List of Checks Specified by Configuration File

Run Model Advisor on a list of checks specified by a Model Advisor configuration file.

Refresh the Model Advisor check information cache to include the files for this example.

Advisor.Manager.refresh_customizations()

Use the example configuration file demoConfiguration.json to specify which checks to include in the Model Advisor analysis. Save the filename demoConfiguration.json to the variable fileName.

fileName = 'demoConfiguration.json';

Create a folder named +MyEditTimeChecks and save the class definition file in that folder.

copyfile PortColor.m* +MyEditTimeChecks

Create a list of the subsystems sldemo_auto_climatecontrol/Heater Control and sldemo_auto_climatecontrol/AC Control.

systems = {'sldemo_auto_climatecontrol/Heater Control',...
    'sldemo_auto_climatecontrol/AC Control'};

Use Model Advisor to run the checks specified by the configuration file demoConfiguration.json on the subsystems specified by systems.

results = ModelAdvisor.run(systems,'Configuration',fileName);

Updating Model Advisor cache...
Model Advisor cache updated. For new customizations, to update the cache, use the Advisor.Manager.refresh_customizations method.
         Running Model Advisor... ... 

         Systems passed: 2 of 2

         Systems with information: 0 of 2

         Systems with warnings: 2 of 2

         Systems with failures or incomplete run: 0 of 2

         Systems with justifications: 0 of 2
         Summary Report

Use Model Advisor to Generate Report

Use Model Advisor to run the checks and generate a report.

Open the model vdp by entering:

openExample('vdp')

Create a list of check IDs. The check ID for the check Check signal line connections is 'mathworks.jmaab.db_0032' and the check ID for the check Check trigger signal names is 'mathworks.jmaab.jc_0281'.

checkIDs = {'mathworks.jmaab.db_0032','mathworks.jmaab.jc_0281'}

Use Model Advisor to run the checks on the model. Use the name-value arguments 'ReportFormat', 'ReportPath', and 'ReportName' to generate as a Microsoft^® Word document in the current folder pwd.

ModelAdvisor.run('vdp', checkIDs,...
'ReportFormat', 'docx', 'ReportPath', pwd, 'ReportName', 'myReport')

For more information on Model Advisor checks and subchecks, see Model Advisor Checks Documentation. For details on how to find check IDs, see Find Model Advisor Check IDs.

Input Arguments

Systems — List of valid models or subsystems

cell array of model names | cell array of subsystem names

List of valid models or subsystems, specified as a cell array of model names or subsystem names.

Example: {'vdp', 'sldemo_2counters'}

Example: {'sldemo_auto_climatecontrol/Heater Control', 'sldemo_auto_climatecontrol/AC Control'}

CheckIDList — List of valid check IDs

character vector | cell array of character vectors

List of valid check IDs for the Model Advisor checks, specified as a character vector or cell array of character vectors.

For information on how to find check IDs, see Find Model Advisor Check IDs.

Do not include duplicate check IDs in CheckIDList. If you need to run the same check multiple times, but with different input parameters, use either of the following approaches:

• Call ModelAdvisor.run separately for each different input parameter.

  For example, to run the check 'mathworks.jmaab.jc_0281' twice, once with the subcheck 'jc_0281_a' disabled and once with the subcheck 'jc_0281_a2' selected:

  myCheck = 'mathworks.jmaab.jc_0281';
  inputParam1 = {'jc_0281_a',0}; % disable 'jc_0281_a' subchecks
  inputParam2 = {'jc_0281_a',2}; % select subcheck 'jc_0281_a2'
  
  ModelAdvisor.run(modelName,{{myCheck,'InputParam',inputParam1}})
  ModelAdvisor.run(modelName,{{myCheck,'InputParam',inputParam2}})
  

• Create and run a Model Advisor configuration that uses separate check instances for each different input parameter. In the Model Advisor Configuration Editor, create a new folder for each different input parameter that you want to run, copy the check into each folder, and modify the checks in each folder to specify different input parameters. Use the ModelAdvisor.run(Systems,'Configuration',FileName) syntax to run the configuration.

Example: 'mathworks.jmaab.jc_0281'

Example: {'mathworks.maab.jc_0021', 'mathworks.misra.BlockNames'}

CheckID — Valid check ID

character vector

Valid check ID for a Model Advisor check, specified as a character vector.

For information on how to find check IDs, see Find Model Advisor Check IDs.

Example: 'mathworks.jmaab.jc_0281'

paramName — Name of input parameter

character vector

The name of an input parameter for a Model Advisor check, specified as a character vector.

You can view the input parameter names for a Model Advisor check by using getInputParameters on a Simulink.ModelAdvisor object. The input parameter name, Name, is a property of the ModelAdvisor.InputParameter object. For more information, see Use Model Advisor to Run Subchecks.

You can also view the input parameters for a check in the Model Advisor Configuration Editor. You can save the input parameter values to your custom Model Advisor configuration file. For more information, see Use Model Advisor Configuration Editor to Customize Model Advisor.

For more information on Model Advisor checks, subchecks, and input parameters, use the links to product-specific check documentation in Model Advisor Checks Documentation.

Example: 'Follow links'

Example: 'jc_0281_a'

paramValue — Value of input parameter

character vector | integer

Value of an input parameter for a Model Advisor check, specified as a character vector or integer.

You can view the input parameter values for a Model Advisor check by using getInputParameters on a Simulink.ModelAdvisor object. The current input parameter value, Value, is a property of the ModelAdvisor.InputParameter object. For more information, see Use Model Advisor to Run Subchecks.

You can also view the input parameters for a check in the Model Advisor Configuration Editor. You can save the input parameter values to your custom Model Advisor configuration file. For more information, see Use Model Advisor Configuration Editor to Customize Model Advisor.

For more information on Model Advisor checks, subchecks, and input parameters, use the links to product-specific check documentation in Model Advisor Checks Documentation.

Example: 'off'

Example: 4

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: results = ModelAdvisor.run(systems,'Configuration',fileName,'ExtensiveAnalysis','Off');

Configuration — Full file name or path of the configuration file

character vector

Full file name or path of the configuration file, specified as a character vector in .json or .mat formats. For details on creating a configuration file, see Use Model Advisor Configuration Editor to Customize Model Advisor.

Example: 'demoConfiguration.json'

Note

If CheckIDList is specified, then you cannot specify Configuration.

DisplayResults — Result display setting

'Summary' (default) | 'Details' | 'None'

Result display setting for Model Advisor, specified as 'Summary', 'Details', or 'None'. Setting DisplayResults to 'Summary' displays a summary of the system results in the Command Window. Setting DisplayResults to 'Details' displays:

• Which system Model Advisor is checking while the run is in progress

• The pass and fail results of each check for each system

• A summary of the system results

Setting DisplayResults to 'None' displays no information in the Command Window.

Example: 'Details'

ExtensiveAnalysis — Extensive analysis setting

'On' (default) | 'Off'

Extensive analysis setting for Model Advisor, specified as 'On' or 'Off'. Setting 'ExtensiveAnalysis' to 'On' runs each of the checks in your Model Advisor configuration, including checks that trigger extensive analysis. Setting 'ExtensiveAnalysis' to 'Off' runs only checks that do not trigger extensive analysis.

Checks that trigger extensive analysis of the model use additional analysis techniques, such as analysis with Simulink^® Design Verifier™. The checks that trigger extensive analysis have the icon in front of the check name in Model Advisor.

To use the 'ExtensiveAnalysis' name-value argument, you must specify a check configuration filename with the 'Configuration' argument.

Example: 'Off'

Force — Force delete setting

'Off' (default) | 'On'

Force delete setting for Model Advisor, specified as 'Off' or 'On'. Setting Force to 'On' removes existing modeladvisor/system folders. Setting Force to 'Off' prompts you before removing existing modeladvisor/system folders.

Example: 'On'

Justifications — Full filename or path to justifications file

string scalar | character vector

Full filename or path to justifications file, specified as a string scalar or character vector. Justifications files are in the JSON format.

For information on how to create a justifications file, see Justify Model Advisor Violations from Check Analysis.

Example: 'vdp_justifications.json'

Data Types: char | string

ParallelMode — Parallel execution setting

'Off' (default) | 'On'

Parallel execution setting for Model Advisor, specified as 'Off' or 'On'. Setting ParallelMode to 'On' runs Model Advisor in parallel mode if you have a Parallel Computing Toolbox™ license and a multicore machine. Each parallel process runs checks on one model at a time. In parallel mode, load the model data from the model workspace or data dictionary. In parallel mode, Model Advisor does not support model data in the base workspace. For an example, see Create Function to Check Multiple Systems.

Note

Model Advisor parallel run is not supported in Simulink Online.

Note

The use of parfor loops with the ModelAdvisor.run command is not recommended. Use the setting ParallelMode instead.

Example: 'On'

ShowExclusions — Report exclusion display setting

'On' (default) | 'Off'

Report exclusion display setting for the report, specified as 'On' or 'Off'. Setting ShowExclusions to 'On' lists Model Advisor check exclusions in the report. Setting ShowExclusions to 'Off' does not list Model Advisor check exclusions in the report.

Example: 'Off'

TempDir — Temporary working folder setting

'Off' (default) | 'On'

Temporary working folder setting for Model Advisor, specified as 'Off' or 'On'. Setting TempDir to 'On' runs Model Advisor from a temporary working folder to avoid concurrency issues when running using a parallel pool. For more information, see Resolving Data Concurrency Issues. Setting TempDir to 'Off' runs Model Advisor in the current working folder.

Example: 'On'

ReportFormat — Format of generated report

'html' (default) | 'pdf' | 'docx'

Format of the generated report, specified as HTML format, PDF format, or Microsoft Word document format.

Note

Model Advisor displays an error if unsupported formats are selected. For the Windows^® operating system with Microsoft Word license, the supported formats are 'html', 'pdf', and 'docx'. For UNIX^®-like operating systems, the only supported format is 'html'.

Example: 'docx'

ReportPath — Path to folder for generated report

'slprj/modeladvisor/modelName' (default) | character vector

Path to the folder for the generated report, specified as a character vector. By default, 'ReportPath' is the 'slprj/modeladvisor/modelName' folder in the current working directory.

Example: 'C:\MyProject\MyReports'

ReportName — File name of the Model Advisor report

'report' (default) | character vector

Model Advisor report file name (without the extension), specified as a character vector.

Example: 'MyReport'

Output Arguments

Results — Model Advisor check results

cell array of ModelAdvisor.SystemResult objects

Model Advisor check results, specified as a cell array of ModelAdvisor.SystemResult objects. The function returns one object for each model or subsystem specified by the input argument Systems.

Each ModelAdvisor.SystemResult object contains a CheckResultObjs property that contains an array of ModelAdvisor.CheckResult objects, one for each check run by ModelAdvisor.run.

To review the results without rerunning Model Advisor, save the results. For more information, see Default Save and Load Process for Objects.

Limitations

• ModelAdvisor.run pre-checks for licenses and errors out if a license is not available.

• ModelAdvisor.run does not run across model hierarchies. To run Model Advisor on a parent model and its referenced models, use Advisor.Application instead.

• ModelAdvisor.run only runs Model Advisor on active variants. To run Model Advisor on both active and inactive variants, use Advisor.Application with the AnalyzeVariants argument specified as true.

Tips

• When you run Model Advisor from the MATLAB^® command line, you can log information such as errors, warnings and debug details by using the LogVerbosity option in the ModelAdvisor.run command.

  ModelAdvisor.run('vdp',checkIDlist,'LogVerbosity','None')

  To specify the level of detail of the logging, you can set the LogVerbosity option as shown:

  Value of LogVerbosity	Level of Information Logging
  None	No information (default value).
  Concise	Moderate amount of information like errors and warnings.
  Verbose	Complete information.

  Additionally, you can include the LogFile option to save the log details to a text file.

  ModelAdvisor.run('vdp',checkIDlist,'LogVerbosity','Concise','LogFile','Log.txt')

  Note

  If LogVerbosity is set to None (the default value), you will not be able to specify the LogFile.

• If you have a Parallel Computing Toolbox license and a multicore machine, Model Advisor can run on multiple systems in parallel. You can run Model Advisor in parallel mode by using ModelAdvisor.run with 'ParallelMode' set to 'On'. By default, 'ParallelMode' is set to 'Off'. When you use ModelAdvisor.run with 'ParallelMode' set to 'On', MATLAB automatically creates a parallel pool.

Alternatives

• Use the Model Advisor user interface to run each system. In the user interface, you can run only one system at a time.

• Create a script or function by using a Simulink.ModelAdvisor object to run each system one at a time.

Extended Capabilities

Automatic Parallel Support

Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

To run in parallel, set 'ParallelMode' to 'On'.