---

name: simulink-collect-metrics description: > Collect and assess quality metrics for Simulink models using the metric.Engine API. Use when evaluating model design quality (maintainability, complexity, architecture) or testing completeness (unit testing, SIL, PIL, coverage, pass rates) after edits or test runs. Covers metric discovery, collection, report generation, and diagnostics. Triggers on: "collect metrics", "quality metrics", "metric.Engine", "testing metrics", "maintainability metrics", "SIL metrics", "PIL metrics", "what metrics are available", "assess quality", "coverage metrics", "generate metric report", "diagnose metric errors". license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.0.0"

Collect Quality Metrics

Assess the quality and completeness of model edits and testing work using metric.Engine. This skill teaches the canonical workflow for discovering, collecting, and interpreting quality metrics across releases.

When to Use

• After editing a model — assess maintainability, complexity, or design quality
• After running tests — assess coverage, pass rates, requirements traceability
• When asked to collect or check quality metrics from a MATLAB project
• When diagnosing why metrics show errors or missing data
• When generating metric reports (HTML, PDF)
• When asked what metrics are available for a project

When NOT to Use

• No MATLAB project is open — metric.Engine requires an open project
• Writing or running tests — use matlab-testing
• Static code analysis or coding standards — use matlab-review-code
• Model Advisor compliance checks — use checking-model-compliance
• Building or editing Simulink models — use building-simulink-models
• Digital thread configuration (digitalthread.settings)
• Requirements authoring (slreq APIs)
• Custom metric authoring (writing new metric algorithms)
• Threshold customization

Workflow

A project must be open before using metric.Engine.

1. Create Engine

me = metric.Engine;

One instance per session is sufficient. Do not create multiple engines.

2. Attach Progress Monitor (Optional)

For progress visibility during updateArtifacts, attach a listener to the project's existing digital thread artifact service.

Setup: Add the skill's scripts/ directory to MATLAB's path before creating the monitor:

addpath("SKILL_DIR/scripts");
projectRoot = currentProject().RootFolder;
pm = AgentProgressMonitor(projectRoot);

Replace SKILL_DIR with the absolute path to this skill's directory on disk.

Ordering matters: Call addpath before AgentProgressMonitor(...). Adding the path after creating the monitor can trigger duplicate progress events from the artifact service re-indexing.

Script: scripts/AgentProgressMonitor.p — prints [dt XX%] message progress lines to stdout during artifact updates.

• Input: projectRoot (string) — the project root folder
• Output: AgentProgressMonitor handle object (clear it to stop listening)

The monitor stays active until cleared. Call updateArtifacts(me) normally — progress prints automatically while the monitor is in scope.

3. Update Artifacts

updateArtifacts(me);

Call updateArtifacts before collecting metrics that relate to testing (ModelUnitTesting, ModelUnitSILTesting, ModelUnitPILTesting, ProjectModelTesting). It refreshes traceability data so results reflect the current project state. Skipping this step produces stale or empty results for testing metrics.

For design/maintainability metrics (ModelMaintainability), updateArtifacts is not strictly required but is harmless.

4. Discover Metric IDs

ids = getAvailableMetricIds(me, App="DashboardApp", Dashboard="ModelUnitTesting");

Never hardcode metric IDs. IDs change across releases. Invalid IDs fail silently (warning + 0 results, no exception). Always discover first.

Valid Dashboard values: see references/metric-groups.md for the full list, introduction releases, and scoping rules.

To collect all installed metrics regardless of dashboard:

allIds = getAvailableMetricIds(me);

5. Execute Collection

execute(me, ids);

Runs the metric algorithms. In R2026a+, execute also returns results directly, but always call getMetrics for cross-release compatibility.

6. Retrieve Results

results = getMetrics(me, ids);

Returns a metric.Result array. Each element has properties: .Value, .MetricID, .Scope, .Artifacts, .Diagnostics.

7. Inspect and Present Results

Identify components with .Scope.Name — this is the model or component name each result belongs to. Do not rely on .Artifacts (frequently empty).

for k = 1:numel(results)
    componentName = results(k).Scope.Name;
    v = results(k).Value;
    if ismissing(v)
        fprintf("%s: No data\n", componentName);
    elseif isstruct(v) && isfield(v, 'Failed')
        fprintf("%s: %d passed, %d failed\n", componentName, v.Passed, v.Failed);
    elseif isnumeric(v) && isscalar(v)
        fprintf("%s: %g\n", componentName, v);
    elseif isstruct(v)
        fprintf("%s: struct(%s)\n", componentName, strjoin(string(fieldnames(v)), ", "));
    end
end

Group results by component when presenting to users:

scopeNames = arrayfun(@(r) string(r.Scope.Name), results(:));
for component = unique(scopeNames).'
    componentResults = results(scopeNames == component);
    fprintf("--- %s (%d metrics) ---\n", component, numel(componentResults));
    % ... summarize key metrics for this component
end

Value shapes vary by metric type and release. Common shapes include: scalar doubles, distribution structs, coverage breakdown structs, named count structs, and linkage ratios. Struct fields may themselves be structs or non-numeric — use disp or fprintf("%g", val) only after confirming isnumeric. See references/release-notes.md for cross-release differences.

Value semantics:

| Metric pattern | Value meaning | Do NOT assume | |----------------|---------------|---------------| | *Complexity, *CyclomaticComplexity | Unbounded positive integer (higher = more complex) | Not a percentage | | *HalsteadDifficulty | Unbounded positive double (higher = harder to maintain) | Not a percentage | | *Distribution | Struct with BinCounts/BinEdges (histogram). BinEdges may be numeric or categorical (cell array of strings). Ratios may be NaN when counts are zero. | Do not format NaN as a number; do not assume numeric bin edges | | Overall*, *Count, *Lines, *Blocks | Raw integer counts | Not bounded |

Coverage metrics return structs whose fields vary by metric prefix and release. Use fieldnames(v) to discover the shape. Common patterns on R2026a:

• slcomp.mt.CoverageBreakdown: nested struct {Execution, Decision, Condition, MCDC, OverflowSaturation}, each with sub-fields {Achieved, Justified, Missed, AchievedOrJustified} (percentages 0–100)
• UnitBoundary*CoverageBreakdown, Requirements*CoverageBreakdown: flat struct {Numerator, Denominator, Value} where Value is a ratio 0–1
• *CoverageFragment: same shape as its *Breakdown counterpart on the same prefix

Do not assume a single coverage struct shape applies to all coverage metrics. Inspect with fieldnames before accessing fields.

Interpreting empty results:

| Value | Meaning | What to tell the user | |-------|---------|----------------------| | [] (empty double) | Prerequisite not met (e.g., tests not run, coverage not collected) | "No test data — run tests first" | | 0 | Metric is applicable but the measured quantity is zero | Report as zero | | ismissing(v) | Metric does not apply to this component | Omit from summary or label "N/A" | | Struct with all-empty sub-fields (e.g., .Achieved = []) | Same as [] — prerequisite not met | "No coverage data — run tests first" |

Summarizing large result sets: Multi-dashboard collection can return 100+ results. Focus on headline metrics per dashboard rather than dumping all results:

| Dashboard | Headline metrics (present first) | Detail metrics (show on request) | |-----------|----------------------------------|----------------------------------| | ModelMaintainability | slcomp.OverallCyclomaticComplexity, slcomp.HalsteadDifficulty, slcomp.OverallBlocks | *Distribution, per-language breakdowns | | ModelUnitTesting | slcomp.mt.TestStatusDistribution, slcomp.mt.CoverageBreakdown | Requirements*, TestCase* distributions | | ModelUnitSILTesting | slcomp.sil.TestStatusDistribution, slcomp.sil.CoverageBreakdown | B2B status, model-level coverage | | ModelUnitPILTesting | slcomp.pil.TestStatusDistribution, slcomp.pil.CoverageBreakdown | B2B status, model-level coverage |

Pattern: present one row per component with headline values, then offer detail on request.

8. Generate Report

When a user asks to "collect metrics" or "assess quality," prefer generateReport as the primary output — it produces a formatted, interactive view with proper component names and visual indicators. Use programmatic inspection (Step 7) when the user needs specific values extracted, when running in CI/headless mode, or when answering targeted questions about individual metrics.

generateReport(me, Dashboard="ModelUnitTesting", Type="html-file", Location=pwd);

| Argument | Values | |----------|--------| | Dashboard | Same values as getAvailableMetricIds | | Type | "pdf" (default), "html-file" | | Location | Output file path or directory (string). If a directory, the filename is auto-generated. | | LaunchReport | true (default) or false for CI |

Available from R2021a. In R2026a+, Dashboard is mandatory.

Key Functions

All functions below are available from R2023a (the minimum release for this skill) unless noted otherwise.

| Function | Purpose | |----------|---------| | metric.Engine | Create engine instance (requires open project) | | updateArtifacts(me) | Refresh artifact traceability index | | getAvailableMetricIds(me) | Discover installed metric IDs | | execute(me, ids) | Run metric collection | | getMetrics(me, ids) | Retrieve collected results | | generateReport(me, ...) | Generate HTML/PDF report | | getArtifactIssues(me) | Return diagnostic warnings/errors | | getArtifactErrors(me) | Return artifact-level errors | | executeDashboardMetrics(me, Dashboard=d) | Convenience: discover + execute (no output; call getMetrics after). Does NOT accept App. Primarily for ProjectModelTesting. R2026a+ |

Patterns

Collect Metrics for a Single Dashboard

me = metric.Engine;
updateArtifacts(me);
ids = getAvailableMetricIds(me, App="DashboardApp", Dashboard="ModelUnitTesting");
execute(me, ids);
results = getMetrics(me, ids);

Collect Across Multiple Dashboards

Use the try-catch pattern in references/metric-groups.md § "Pattern: Safe Multi-Dashboard Collection".

Generate Report

me = metric.Engine;
ids = getAvailableMetricIds(me, App="DashboardApp", Dashboard="ModelMaintainability");
execute(me, ids);
generateReport(me, Dashboard="ModelMaintainability", Type="html-file", Location=pwd);

Do NOT build HTML manually with fopen/fprintf. Use the built-in generateReport.

Diagnose Artifact Issues

When metrics show errors or return empty results, use getArtifactIssues and getArtifactErrors to diagnose the problem — do not manually inspect project files, .prj internals, data dictionaries, or file paths as a workaround.

me = metric.Engine;
issues = getArtifactIssues(me);
errors = getArtifactErrors(me);
if ~isempty(issues)
    disp(issues);
end
if ~isempty(errors)
    disp(errors);
end

CI / Headless Usage

me = metric.Engine;
updateArtifacts(me);
ids