metric.Engine

R2026b

Collect metric results

Description

A metric.Engine object represents the metric engine that you can execute with the execute object function to collect metric results. Use getMetrics to access the metric results and return an array of metric.Result objects. Use the metric results to assess the status and quality of your design. Use the model maintainability metrics to analyze the maintainability and complexity of the design. Use the model and code testing metrics to analyze artifacts such as requirements, test results, and coverage results. For additional metrics, see Design Cost Model Metrics (Fixed-Point Designer).

Creation

Syntax

metric_engine = metric.Engine()

metric_engine = metric.Engine(projectPath)

Description

metric_engine = metric.Engine() creates a metric engine object that collects metric results on the current project.

metric_engine = metric.Engine(projectPath) opens the project projectPath and creates a metric engine object that collects metric results on the project.

Input Arguments

projectPath — Path of project

character vector | string scalar

Path of the project for which you want to collect metric results, specified as a character vector or string scalar.

Properties

ProjectPath — Project for metric collection

Read-only: string scalar

This property is read-only.

Project for which the engine collects metric results, returned as a string.

Object Functions

deleteAllMetrics	Delete all metric results
deleteMetrics	Delete specific metric results
execute	Collect metric results
executeDashboardMetrics	Collect metrics for specific dashboard
generateReport	Generate report file containing metric results
getArtifactErrors	View errors from artifact analysis
getArtifactIssues	View issues from artifact analysis
getAvailableMetricIds	Return metric identifiers for available metrics
getMetrics	Access metric results
getThresholdSets	Get available threshold sets for project
openArtifact	Open traced artifact from metric result
updateArtifacts	Update trace information for pending artifact changes in the project

Examples

Collect Metric Results on Design Artifacts in Project

Use a metric.Engine object to collect metric results on the design artifacts in a project.

Open a project containing models that you want to analyze. For this example, in the MATLAB^® Command Window, enter:

openExample("slcheck/ExploreTestingMetricDataInModelTestingDashboardExample");
openProject("cc_CruiseControl");

Create a metric.Engine object. To collect the metric results for the current project, use the metric.Engine object.

metricEngine = metric.Engine();

To collect results for a model design metric, execute the metric engine. The execute function returns the collected results. For more information on the model design metrics, see Model Design Metrics and Model Maintainability Metrics.

results = execute(metricEngine,"sldesignlayer.SimulinkDesignInfo")

results =

  1x45 Result array with properties:

    UserData
    Value
    MetricID
    Artifacts
    ScopeId
    ScopeAlias
    ThresholdOutcomes
    Diagnostics

To access the metric results data, use the properties of the metric.Result objects in the results array. For this metric, the Value property is a structure containing design information for each component in the model.

v = results(1).Value

v =

  struct with fields:

            Blocks: 7
         Decisions: 4
             Gotos: 0
    InterfacePorts: [1x1 struct]
       SignalLines: 18
          Halstead: [1x1 struct]

v.InterfacePorts

ans =

  struct with fields:

     In: 3
    Out: 1

v.Halstead

ans =

  struct with fields:

     TotalOperators: 11
    UniqueOperators: 7
      TotalOperands: 15
     UniqueOperands: 12
             Volume: 110.4461
         Difficulty: 4.3750

Display specific design information across all model layers by building a table from the results.

modelLayers = [results.ScopeAlias].';
values = [results.Value].';
signalLines = [values.SignalLines].';
T = table(modelLayers,signalLines,VariableNames=["Model Layer","Signal Lines"])

T =

  45×2 table

                 Model Layer                 Signal Lines
    _____________________________________    ____________

    "Target_Speed_Calculator"                     18     
    "Switch Case Action↵Subsystem3"                1     
    "Transitions_From_THROTTLE_OVERRIDE"          14   
    ...

To access collected results or a subset of those results after execution, use getMetrics.

results = getMetrics(metricEngine,"sldesignlayer.SimulinkDesignInfo");

Model design metrics provide high-level design information about models. Model maintainability metrics provide more detailed metric results. For more information on how to collect metrics for design artifacts, see Collect Model Maintainability Metrics Programmatically.

Collect Metric Results on Testing Artifacts in Project

Use a metric.Engine object to collect metric results on the requirements-based testing artifacts in a project.

Open a project that contains models and testing artifacts. For this example, in the MATLAB Command Window, enter:

openExample("slcheck/ExploreTestingMetricDataInModelTestingDashboardExample");
openProject("cc_CruiseControl");

Create a metric.Engine object. You can use the metric.Engine object to collect metric results for the current project.

metricEngine = metric.Engine();

Collect results for model testing metrics by executing the metric engine. The execute function returns the collected results.

results = execute(metricEngine,"modeltesting.TestAnalysis[]")

results =

  1x44 Result array with properties:

    UserData
    Value
    MetricID
    Artifacts
    ScopeId
    ScopeAlias
    ThresholdOutcomes
    Diagnostics

Use getMetrics to access a subset of the collected results. For example, get only the results for the ratio of requirements per test.

reqsPerTest = getMetrics(metricEngine,"modeltesting.TestAnalysis[slcomp.RequirementsPerTestRatio]")

reqsPerTest =

  1x4 Result array with properties:

    UserData
    Value
    MetricID
    Artifacts
    ScopeId
    ScopeAlias
    ThresholdOutcomes
    Diagnostics

Access the metric results data by using the properties of the metric.Result objects in the array. For this metric, the Value property is a structure containing the total, linked, and unlinked requirement counts.

reqsPerTest(1).Value

ans =

  struct with fields:

       Total: 37
      Linked: 37
    Unlinked: 0

reqsPerTest(1).ScopeAlias

ans =

    "cc_ControlMode"

Display the ratio of requirements per test for each unit model in the project.

models = [reqsPerTest.ScopeAlias].';
values = [reqsPerTest.Value].';
total = [values.Total].';
linked = [values.Linked].';
unlinked = [values.Unlinked].';
T = table(models,total,linked,unlinked,VariableNames=["Model","Total","Linked","Unlinked"])

T =

  4x4 table

           Model              Total    Linked    Unlinked
    ____________________      _____    ______    ________

    "cc_ControlMode"           37        37         0
    "cc_LightControl"           5         5         0
    "cc_DriverSwRequest"       10        10         0
    "cc_ThrottleController"     0         0         0

For more information on how to collect metrics for testing artifacts, see Collect Metrics on Model Testing Artifacts Programmatically.

Version History

Introduced in R2020b