execute

R2026b

Collect metric results

collapse all in page

Syntax

results = execute(metricEngine,metricIDs)
results = execute(___,Name=Value)

Description

results = execute(metricEngine,metricIDs) collects results in the specified metric.Engine object for the metrics that you specify in metricIDs.

There is also a function execute (Fixed-Point Designer) in the Fixed-Point Designer™ documentation.

example

results = execute(___,Name=Value) specifies options using one or more name-value arguments in addition to the input arguments in previous syntaxes. For example, you can specify the ScopeId to collect metrics for a specific artifact in your project.

example

Examples

collapse all

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 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.

Collect metrics for one unit in the project. Specify a model and collect metrics for only the artifacts that trace to the model.

Open the project that contains the model. For this example, in the MATLAB Command Window, enter:

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

Create a metric.Engine object for the project.

metric_engine = metric.Engine();

Update the trace information for metric_engine to ensure that the artifact information is up to date.

updateArtifacts(metric_engine)

Open the model cc_DriverSwRequest and find the digital thread URI for that model.

open_system("cc_DriverSwRequest");
storageMap = digitalthread.StorageMap.forProject();
modelURI = digitalthread.uri.simulink.fromObject(storageMap,get_param(gcs,"Handle"))

Collect results for a model testing metric by using the execute function on the engine object and limiting the scope to the cc_DriverSwRequest model.

results = execute(metric_engine,"modeltesting.TestAnalysis[slcomp.RequirementsPerTestRatio]",ScopeId=modelURI)

Access the metric results data by using the properties of the metric.Result object.

results.Value
ans =

  struct with fields:

       Total: 10
      Linked: 10
    Unlinked: 0

You can scope metric result collection to a specific artifact by using a digital thread URI. A digital thread URI uniquely identifies an artifact, such as a model, subsystem, or block, so that the metric engine collects results only for that artifact.

Get the digital thread URI for the artifact that you want to collect metrics for. You can find digital thread URIs by using the functions in the digitalthread.uri namespace. For example, to find the digital thread URI for a subsystem that you select in a Simulink® model:

storageMap = digitalthread.StorageMap.forProject();
subsystemURI = digitalthread.uri.simulink.fromObject(storageMap,get_param(gcb,"Handle"))
subsystemURI = 

    "mwdigitalthread://myProject/myModel.slx#addr=myModel/123"

Collect metrics for that specific subsystem by passing the artifact URI to the ScopeId argument.

metricID = "sldesignlayer.SimulinkDesignInfo";
results = execute(metric_engine,metricID,ScopeId=subsystemURI)
results = 

  Result with properties:

             UserData: ''
                Value: [1×1 struct]
             MetricID: 'sldesignlayer.SimulinkDesignInfo'
            Artifacts: [1×1 struct]
              ScopeId: "mwdigitalthread://myProject/myModel.slx#addr=myModel/308"
           ScopeAlias: "mySubsystem"
    ThresholdOutcomes: [1×0 metric.threshold.ThresholdOutcome]
          Diagnostics: []
The metric engine only collects metric results for the specified artifact.

Input Arguments

collapse all

Metric engine object for which you want to collect metric results, specified as a metric.Engine object.

Metric identifiers for metrics that you want to collect, specified as a character vector, cell array of character vectors, string, or string array.

You can use the function getAvailableMetricIds to return a list of available metric identifiers.

For information on the metrics and their identifiers, see:

Example: 'slcomp.OverallCyclomaticComplexity'

Example: {'slcomp.OverallMATLABeLOC', 'slcomp.OverallSignalLines'}

Example: 'TestCasesPerRequirementDistribution'

Example: {'slcomp.mt.TestStatus', 'slcomp.mt.CoverageBreakdown'}

Name-Value Arguments

collapse all

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.

Example: results = execute(metric_engine,"modeltesting.TestAnalysis[slcomp.RequirementsPerTestRatio]",ScopeId=modelURI)

Digital thread URI for the artifact that you want to collect metric results for, specified as a string scalar.

A digital thread URI is a stable identifier for an artifact, such as a model file, or a sub-file artifact, such as a block. The digital thread uses these URIs as a consistent way to refer to artifacts across tools and inside metric results. The scopes that a metric supports depend on the metric. Check the metric documentation to learn what scopes a metric operates on, and use the appropriate function from the digitalthread.uri namespace to get the URI for the artifact. For example, use digitalthread.uri.simulink.fromObject to get the URI for a model or element within a model.

Note

If you specify both ScopeId and ArtifactScope, ScopeId takes precedence.

Note

For table metrics (metrics that use the bracket notation, such as "modeldesign.SimulinkMaintainability[slcomp.BlockDistribution]"), specifying ScopeId does not limit the scope of the table metric itself. The table metric still collects results across all scopes. The ScopeId argument only limits the collection of dependent metrics that the table metric imports. For non-table metrics, ScopeId limits the collection to the specified artifact.

Example: "mwdigitalthread://myProject/myModel.slx#addr=myModel/###"

Data Types: string

Since R2026b

Threshold set identifier, specified as a string scalar. Use this argument to classify metric results according to a specific threshold set. The threshold set determines how metric values are classified into compliance categories.

The shipping threshold sets are "Testing" and "ReqBasedTesting". You can also specify custom threshold sets that you create by using metric.config.Configuration.copyThresholdSet on a metric.config.Configuration object.

Example: "Testing"

Example: "MyTestingThresholds"

Data Types: string

Output Arguments

collapse all

Metric results, returned as an array of metric.Result objects.

When you execute a table metric with a specific sub-metric identifier, such as "modeltesting.TestAnalysis[slcomp.TestTagDistribution]", the Value property of the result contains the sub-metric identifier as a field name. For example, results.Value.TestTagDistribution.

Alternative Functionality

App

You can also collect metric results by using the dashboard user interface.

Version History

Introduced in R2020b

expand all

See Also

| | | | | | | | | |

Topics