matlab/simulink-agentic-toolkit/create-sdi-run

Create SDI Run

Get data into the Simulation Data Inspector using the shortest path that works. Most agents reflexively read files into the workspace and rebuild signals by hand; this skill teaches the direct paths and when each applies.

When to Use

• User has a .mat, .csv, or .xlsx file of logged data and wants to view it in SDI.
• User just ran sim(model) and wants to see the logged signals.
• User has timeseries, timetable, or Simulink.SimulationData.Dataset variables in the workspace and wants an SDI run.
• User asks about Simulink.sdi.createRun, Simulink.sdi.getAllRunIDs, or Simulink.sdi.getRun.

When NOT to Use

• Comparing two existing runs — that is a distinct workflow (Simulink.sdi.compareRuns).
• Streaming data live during a running simulation — this is a separate API (Simulink.sdi.createRunOrAddToStreamedRun), not a mode of createRun. Prompts like "stream data into SDI while my sim is running" belong to that API. Do not activate on those.
• Files in MDF (.mf4), ULG, ROS bag, CAN log, or HDF5 formats — see references/format-support.md for what SDI reads natively vs. what needs a different toolbox.
• Customizing plot layout, cursors, or subplot arrangement beyond opening the SDI window.
• Authoring Gherkin `.feature` files, Simulink Test cases, `matlab.unittest` classes, or any pass/fail assertions or regression tests for a model or subsystem — use testing-simulink-models (Gherkin-based model_test, requires Simulink Test). Prompts like "write a Gherkin test for X", "verify abs(-5) equals 5", "create a regression test for this subsystem", or any request whose deliverable is a test artifact belong there. Do not activate this skill on such prompts even when testing-simulink-models is unavailable — in that case, tell the user which skill is missing and stop.

Workflow

Answer these four questions in order. The first "yes" tells you what to do.

1. Is the data already in SDI?

After sim(model) with signal logging enabled, SDI auto-populates one run. Do not call `createRun` — that produces a duplicate.

before = Simulink.sdi.getAllRunIDs;
simOut = sim("myModel");
after  = Simulink.sdi.getAllRunIDs;
if numel(after) > numel(before)
    Simulink.sdi.view;   % done — just open the window
end

If no new run appeared, logging is off. Enable it via the Simulink Agentic Toolkit model_edit tool with a configure op setting DataLogging on the target port, then re-simulate — or fall back to Step 3 with simOut. As a last resort, ask the user to right-click a signal → Log Selected Signals in the Simulink editor themselves; that step is for the user to perform, not the agent.

2. Is the data in a file?

Use the 'file' source. One call handles MAT, CSV, and Excel natively — no load, no readtable, no sheetnames loop.

runID = Simulink.sdi.createRun("bench_test","file","logs/bench_test.mat");

Excel with N sheets returns a 1×N `int32` vector — one run ID per sheet. All returned runs inherit the base name; if the user needs sheet-named runs, rename each run in place with sheetnames() — do not delete and re-import per sheet:

runIDs = Simulink.sdi.createRun("cases","file","cases.xlsx");   % [id1, id2, ...]
sheets = sheetnames("cases.xlsx");
for k = 1:numel(runIDs)
    Simulink.sdi.getRun(runIDs(k)).Name = sheets(k);
end

Time-column header rule (CSV and Excel). SDI's built-in reader requires the time column to be named literally time (case-insensitive). Headers like time_s, t, Time (s), Timestamp cause SDI:sdi:ImportError. Try `'file'` first and catch the error — do not pre-inspect the header row and guess, because SDI's matching rules can differ from your interpretation. On SDI:sdi:ImportError, fall back to the readmatrix + array2timetable + 'vars' pattern (Step 3 / CSV pattern below). Do not rewrite the source file.

Other `createRun` failures. createRun can also throw for reasons this skill does not enumerate — corrupted files, unsupported data types inside a MAT/Excel, malformed structs, permission errors, unregistered custom readers. When you catch an error identifier that is not SDI:sdi:ImportError, do not invent a fix or silently retry. Surface the full error identifier and message to the user, list the file or variables involved, and suggest they inspect the source (e.g., whos("-file",path) for a MAT, or sheetnames(path) plus a per-sheet read for an Excel). Ask before attempting an alternative import path.

3. Is the data in workspace variables?

Two sources, different purposes:

• `'vars'` — pass variables whose names or .Name properties are already correct. This is the default.
• `'namevalue'` — pass explicit signal names when the variables have no .Name metadata (e.g., bare arrays or unnamed timeseries).

Timeseries whose .Name is already what you want:

% TEMPLATE — not executable
runID = Simulink.sdi.createRun("baseline","vars", speedTS, torqueTS);

Timetable — signals inherit the column names:

% TEMPLATE — not executable
runID = Simulink.sdi.createRun("baseline","vars", benchTT);

Bare arrays needing explicit names:

% TEMPLATE — not executable
runID = Simulink.sdi.createRun("baseline","namevalue", ...
    {"velocity","load"}, {velocityData, loadData});

Gotcha (Gap E): if a timeseries passed to 'namevalue' has its own .Name set, .Name wins over the caller-supplied name. To force the name you want, either set ts.Name first and use 'vars', or clear it before 'namevalue'.

4. Verify the run

After every createRun or auto-populate:

ids = Simulink.sdi.getAllRunIDs;
run = Simulink.sdi.getRun(ids(end));
fprintf("Run %d: %s (%d signals)\n", ids(end), run.Name, run.SignalCount);
for k = 1:run.SignalCount
    fprintf("  %s\n", run.getSignalByIndex(k).Name);
end
Simulink.sdi.view;

Verify against MATLAB via the MATLAB MCP server's evaluate_matlab_code tool. If SignalCount == 0, the import silently produced nothing — investigate the source, do not report success.

Key Functions

All available from R2023a with base Simulink; no additional toolbox required.

Four createRun sources exist: empty, `'vars'`, `'namevalue'`, `'file'`. When unsure, run help Simulink.sdi.createRun.

Patterns

Pattern: MAT file → SDI (one line)

runID = Simulink.sdi.createRun("sensor_log","file","data/sensor_log.mat");
Simulink.sdi.view;

The variables inside the MAT file may be timeseries, timetable, Simulink.SimulationData.Dataset, or legacy struct-with-time — SDI's reader picks them up automatically.

Pattern: CSV file → SDI (try 'file', catch, fall back)

Attempt the one-liner first. On SDI:sdi:ImportError, fall back to the timetable path — do not rewrite the file:

try
    runID = Simulink.sdi.createRun("bench_run","file","logs/bench_run.csv");
catch ME
    if strcmp(ME.identifier,"SDI:sdi:ImportError")
        raw     = readmatrix("logs/bench_run.csv");
        headers = string(readcell("logs/bench_run.csv","Range","1:1"));
        tt = array2timetable(raw(:,2:end), ...
                "RowTimes", seconds(raw(:,1)), ...
                "VariableNames", headers(2:end));
        runID = Simulink.sdi.createRun("bench_run","vars", tt);
    else
        rethrow(ME);
    end
end

Assumes the time column is column 1 and expressed in seconds — the common case for bench logs. If the time column sits elsewhere or uses different units, adjust the index or wrap it with the appropriate duration constructor (milliseconds, minutes, …) before passing to RowTimes.

Pattern: Excel with multiple sheets → one run per sheet

One createRun call per file. Every returned run initially inherits the base name you supplied — SDI does not auto-apply sheet names. Rename in place with sheetnames(); do not delete and re-import per sheet. The same time-column-header rule applies as for CSV — if a sheet's time column is not named time, createRun throws SDI:sdi:ImportError; wrap this call in the same try-then-fallback shown in the CSV pattern, using readmatrix(...,"Sheet",sheets(k)) and readcell(...,"Sheet",sheets(k),"Range","1:1") per sheet.

runIDs = Simulink.sdi.createRun("test_matrix","file","data/two_runs.xlsx");
% runIDs is a 1xN int32 vector — one ID per sheet, all named "test_matrix".
sheets = sheetnames("data/two_runs.xlsx");
for k = 1:numel(runIDs)
    run = Simulink.sdi.getRun(runIDs(k));
    run.Name = sheets(k);   % rename in place to the sheet name
    fprintf("Sheet run: %s (%d signals)\n", run.Name, run.SignalCount);
end

To restrict to specific sheets, use the sheets name-value — the returned vector is trimmed accordingly:

runIDs = Simulink.sdi.createRun("cases","file","cases.xlsx", ...
    sheets=["baseline","variant"]);

Pattern: Post-sim — just open SDI

before = Simulink.sdi.getAllRunIDs;
simOut = sim("controller_test");
after  = Simulink.sdi.getAllRunIDs;
 
if numel(after) > numel(before)
    Simulink.sdi.view;             % logged signals already imported
else
    % No auto-populate — logging is off. Enable it and re-simulate, or
    % pass simOut through createRun as a fallback:
    Simulink.sdi.createRun("run_from_simout","vars", simOut);
    Simulink.sdi.view;
end

Pattern: Rename workspace signals

Set .Name before 'vars'. This avoids the 'namevalue' override trap.

data = load("data/speed_torque.mat");
speed  = data.speed;
torque = data.torque;
speed.Name  = "velocity";
torque.Name = "torqueNm";
runID = Simulink.sdi.createRun("baseline","vars", speed, torque);

Conventions

Always

• Check whether SDI already has the data before calling `createRun`. Use Simulink.sdi.getAllRunIDs before and after sim(model). If a new run appeared, sim already imported the logged signals — call Simulink.sdi.view and stop.
• Prefer the `'file'` source for .mat, .csv, .xlsx. It handles the read and the signal-naming for you. Reserve load/readtable/sheetnames for the CSV time-column fallback and for genuinely workspace-first workflows.
• Verify with `SignalCount`. After every import, confirm at least one signal exists. Zero signals means the import failed silently.
• Read `help Simulink.sdi.createRun` if you are unsure which source applies. The four sources are the entire API surface for import.

Ask First