Simulink.sdi.Run

R2026b

Access run signals and metadata

expand all in page

Description

The Simulink.sdi.Run object contains run metadata and allows you to access the Simulink.sdi.Signal objects that contain data and metadata for the signals in the run. You can also use a Simulink.sdi.Run object to import data into the Simulation Data Inspector from the workspace or a file.

Creation

The Simulation Data Inspector creates Simulink.sdi.Run objects when you import data or simulate a model that logs data. You can access a Run object in the Simulation Data Inspector three ways:

You can also programmatically create a Simulink.sdi.Run object to import data into the Simulation Data Inspector.

  • Create an empty run in the Simulation Data Inspector using the Simulink.sdi.Run.create function.

  • Create an empty run in the Simulation Data Inspector or import data into the Simulation Data Inspector using the Simulink.sdi.createRun.

Tip

Use the add function or the Simulink.sdi.addToRun function to import data into an empty Run object.

Properties

expand all

Identification Properties

This property is read-only.

Unique numerical identification for the run, represented as an integer.

Run name, specified as a character vector or string.

By default, the Name property is empty when you use the Simulink.sdi.Run.create function to create a run.

You can specify the run name when you use the Simulink.sdi.createRun function to create a run.

When you create a run by simulating a model that logs data, the run name is generated according to the run-naming rule in the Simulation Data Inspector. You can modify the run-naming rule in the Simulation Data Inspector in the UI or by using the Simulink.sdi.setRunNamingRule function.

Example: 'Run 1: vdp'

This property is read-only.

Storage size of the run in bytes, represented as a positive integer. The storage size accounts for both the data and time vectors of the signals in the run and can be affected by the sample time.

You can also use Simulink.sdi.getSizeInfo to get a table of signal information, including signal storage size, for a run.

Example: 6464

Description of the run, specified as a character vector or string. By default, Description is empty. Use the Description property to add notes about the significance of the data within the run, like the test or simulation conditions used to create the data.

Example: 'Initial simulation'

Tag for additional run information, specified as a character vector or string. By default, Tag is empty. You can use the Tag property to attach additional information to the Run object. For example, you could use the Tag property to include parameter values used for the simulation that created the run in the Run object metadata.

Example: 'Gain = 2'

Date and time the run was created, represented as a datetime object.

Example: 07-Dec-2019 13:55:25

Data Types: datetime

This property is read-only.

Index of the run in the Simulation Data Inspector when the run was created, represented as an integer. The RunIndex matches the run number in the run name when you use the run index as part of the run-naming rule.

If you delete runs from the Simulation Data Inspector, the value of the RunIndex property may not match the index of the run ID in the vector returned by the Simulink.sdi.getAllRunIDs function.

This property is read-only.

Number of signals in the run, represented as an integer.

Simulation Information

Name of the model simulated to create the run, returned as a character vector. The Model property is empty for runs created by importing data into the Simulation Data Inspector.

Simulation mode used in the simulation that created the run, returned as a character vector. The SimMode property is empty for runs created by importing data into the Simulation Data Inspector.

Version of Simulink® used for the simulation that created the run, returned as a character vector. The SLVersion property is empty for runs created by importing data into the Simulation Data Inspector.

Version of the model that was simulated to create the run, returned as a character vector. The version of a model is stored in its model properties. The ModelVersion property is empty for runs created by importing data into the Simulation Data Inspector.

System account used to perform the simulation that created the run, returned as a character vector. The UserID property is empty for runs created by importing data into the Simulation Data Inspector.

Name of the machine used to perform the simulation that created the run, returned as a character vector. The MachineName property is empty for runs created by importing data into the Simulation Data Inspector.

Operating system on the machine used to perform the simulation, returned as a character vector. The Platform property is empty for runs that do not correspond to a simulation.

Example: 'PCWIN64'

Name of the simulation task that corresponds to the run, returned as a character vector. The TaskName property is empty unless the run was created using Parallel Computing Toolbox™ workers.

Type of solver used in the simulation that created the run, returned as 'Variable-Step' or 'Fixed-Step'. The SolverType property is empty for runs created by importing data into the Simulation Data Inspector.

Name of the solver used in the simulation that created the run, returned as a character vector. The SolverName property is empty for runs created by importing data into the Simulation Data Inspector.

Example: ode45

Step size used by the solver during the simulation, returned as a character vector. If the simulation used a fixed-step solver, the SolverStepSize property indicates the fixed step size used in the simulation. If the simulation used a variable-step solver, the SolverStepSize property indicates the maximum step size used in the simulation.

Example: '0.4'

User-specified string that corresponds to the simulation, returned as a character vector. Often, the UserString provides a brief description of the simulation. You specify the UserString for a simulation in the Simulink.SimulationInput object for the simulation.

Timing Properties

First time point shared by all signals in the run, returned as a scalar.

Last time point shared by all signals in the run, returned as a scalar.

Time required to initialize the model for the simulation that created the run, returned as a double. The ModelInitializationTime property is empty for runs created by importing data into the Simulation Data Inspector.

Execution time for the simulation that created the run, returned as a double. The ModelExecutionTime property is empty for runs created by importing data into the Simulation Data Inspector.

Time to terminate the simulation that created the run, returned as a double. The ModelTerminationTime property is empty for runs created by importing data into the Simulation Data Inspector.

Total simulation time for the simulation that created the run, returned as a double. The ModelTotalElapsedTime property is empty for runs created by importing data into the Simulation Data Inspector.

Status Information

Simulation status, returned as a character vector. When the simulation is running, the Status property is 'Running'. When a simulation is paused or completes, the Status property takes the value from the StopEvent field of the Simulink.SimulationMetadata object StopEvent property. The StopEvent property has one of these values:

  • ReachedStopTime — The simulation completed with no reported errors, not including errors reported in the StopFcn callback, which executes after the simulation stops.

  • ModelStop — A block or solver stopped the simulation before the simulation stop time.

  • StopCommand — A Stop button press or set_param function call ended the simulation.

  • DiagnosticError — A reported error ended the simulation.

  • KeyboardControlC — A Ctrl+C keyboard entry ended the simulation.

  • PauseCommand — A Pause button press or set_param function call paused the simulation.

  • ConditionalPause — A conditional breakpoint paused the simulation.

  • PauseTime — A specified pause time paused the simulation.

  • StepForward — The simulation paused after stepping forward while stepping through a simulation.

  • StepBackward — The simulation paused after stepping backward while stepping through a simulation.

  • TimeOut — The simulation stopped after the simulation execution time exceeded the timeout time specified using the 'TimeOut' name-value pair for the sim function.

Block that issued the stop event that stopped the simulation, returned as a Simulink.SimulationData.BlockPath object.

Translated description of the simulation stop, returned as a character vector. The StopEventDescription includes a description of the stop event and the associated simulation time, if applicable. The StopEventDescription property takes its value from the StopEventDescription field of the Simulink.SimulationMetadata object ExecutionInfo property.

Example: 'Pause command issued at time 100'

Errors that occurred during simulation, returned as a character vector.

Warnings that occurred during simulation, returned as a character vector.

Object Functions

addImport data into existing run in Simulation Data Inspector using Simulink.sdi.Run object
exportExport run or signal from the Simulation Data Inspector to workspace or file
getAllSignalIDsGet all signal IDs for signals in Simulink.sdi.Run object
getAllSignalsGet all signals in Simulink.sdi.Run object
getDatasetRefCreate Simulink.sdi.DatasetRef object for run
getSignalByIndexGet signal in Simulink.sdi.Run object by index
getSignalIDByIndexGet signal ID for signal at specified index in Simulink.sdi.Run object
getSignalIDsByNameGet signal IDs for signals inside Simulink.sdi.Run object using signal name
getSignalsByNameAccess signals in a Simulink.sdi.Run object using signal name
isValidSignalIDCheck whether signal ID corresponds to signal in Simulink.sdi.Run object

Examples

collapse all

To plot signals from a Simulink.sdi.Run object in the Simulation Data Inspector, access the signals and use plotOnSubPlot.

Get the most recently created run and check the number of signals.

runObj = Simulink.sdi.Run.getLatest;
numSignals = runObj.SignalCount
numSignals = int32

2

To access a signal in the run, use getSignalByIndex. For example, get the Simulink.sdi.Signal objects for the two signals in the latest run. 

sig1 = getSignalByIndex(runObj,1);
sig2 = getSignalByIndex(runObj,2);

To plot signals in the Simulation Data Inspector, use plotOnSubPlot. To specify subplot layout use Simulink.sdi.setSubPlotLayout. For example, specify a 2-by-1 subplot layout. Then, plot the first signal in the upper subplot and the second signal in the lower subplot. 

Simulink.sdi.setSubPlotLayout(2,1)
plotOnSubPlot(sig1,1,1,true);
plotOnSubPlot(sig2,2,1,true);
Open Live Script

Create a run, add data to it, and then view the data in the active tab of the Simulation Data Inspector.

Create Data for Run

Create two timeseries objects to contain data for a sine signal and a cosine signal. Give each timeseries object a descriptive name.

time = linspace(0,20,101);

sine_vals = sin(2*pi/5*time);
sine_ts = timeseries(sine_vals,time);
sine_ts.Name = "Sine, T=5";

cos_vals = cos(2*pi/8*time);
cos_ts = timeseries(cos_vals,time);
cos_ts.Name = "Cosine, T=8";

Create Run and Add Data

To open the Simulation Data Inspector, use Simulink.sdi.view.

Simulink.sdi.view

To import data into the Simulation Data Inspector from the workspace, create a Simulink.sdi.Run object using Simulink.sdi.Run.create. Add metadata information using the Name and Description properties of the Run object.

sinusoidsRun = Simulink.sdi.Run.create;
sinusoidsRun.Name = "Sinusoids";
sinusoidsRun.Description = "Sine and cosine signals with different frequencies";

Add the data you created in the workspace to the empty run.

add(sinusoidsRun,"vars",sine_ts,cos_ts);
 0.091530s wall, 0.156250s user + 0.031250s system = 0.187500s CPU (204.9%)

Plot Data in Simulation Data Inspector

To access the Simulink.sdi.Signal object corresponding to each signal, use getSignalByIndex. You can use the Simulink.sdi.Signal object properties to specify the line style and color for the signal and plot the signal in the Simulation Data Inspector. For example, specify the LineColor and LineDashed properties for each signal.

sine_sig = getSignalByIndex(sinusoidsRun,1);
sine_sig.LineColor = [0 0 1];
sine_sig.LineDashed = "-.";

cos_sig = sinusoidsRun.getSignalByIndex(2);
cos_sig.LineColor = [1 0 0];
cos_sig.LineDashed = "--";

To configure a 2-by-1 subplot layout in the active tab of the Simulation Data Inspector plotting area, use Simulink.sdi.setSubPlotLayout. To plot the sine signal on the upper subplot and the cosine signal on the lower subplot, use plotOnSubPlot.

Simulink.sdi.setSubPlotLayout(2,1);

plotOnSubPlot(sine_sig,1,1,true);
plotOnSubPlot(cos_sig,2,1,true);

A 2-by-1 subplot layout for Tab1 in the Simulation Data Inspector. The sine signal is plotted in the upper subplot and the cosine signal is plotted in the lower subplot.

Inspect Data Using Cursors

To access the value of a signal at a specific time, you can add a cursor to the plot. For example, the Sine signal appears to have a local maximum at about 6 seconds. Add one cursor to the plot and observe the signal value at 6 seconds.

Simulink.sdi.setNumCursors(1)
Simulink.sdi.setCursorPositions("left",6)

The Simulation Data Inspector with a cursor positioned at 6 seconds in Tab1. The cursor is applied to both subplots.

To measure the time difference between two points or extract descriptive statistics within the defined interval, add two cursors.

Simulink.sdi.setNumCursors(2)
Simulink.sdi.setCursorPositions("left",5,"right",7)

The Simulation Data Inspector with two cursors positioned at 5 seconds and 7 seconds in Tab1.

Determine the local maximum sample value in the Sine signal between the cursors using the max function. 

[t1,t2] = Simulink.sdi.getCursorPositions;
localMax = max(sine_sig,t1,t2)
localMax = 
0.9980

Close Simulation Data Inspector and Save Data

When you finish inspecting the plotted signal data, you can close the Simulation Data Inspector and save the session to an MLDATX file.

Simulink.sdi.close("sinusoids.mldatx")

This example uses:

Open Live Script

Execute parallel simulations of the model ThreeSigs with different input filter time constants and access the data in different ways using the Simulation Data Inspector programmatic interface.

Setup

Clear the Simulation Data Inspector and check that Parallel Computing Toolbox™ support is configured to import runs created on local workers automatically. Then, create a vector of filter parameter values to use in each simulation.

Simulink.sdi.clear
Simulink.sdi.enablePCTSupport("local")

Ts_vals = [0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1];

Initialize Parallel Workers

Use the gcp function to create a pool of local workers to run parallel simulations if you don't already have one. In an spmd code block, load the ThreeSigs model and select signals to log. To avoid data concurrency issues using sim in parfor, create a temporary directory for each worker to use during simulations. 

p = gcp;
spmd
    load_system("ThreeSigs")
    workDir = pwd;
    addpath(workDir)
    tempDir = tempname;
    mkdir(tempDir)
    cd(tempDir)
end

Run Parallel Simulations

Use parfor to run the seven simulations in parallel. Select the value for Ts for each simulation, and modify the value of Ts in the model workspace. Then, run the simulation and build an array of Simulink.sdi.WorkerRun objects to access the data with the Simulation Data Inspector. After the parfor loop, use another spmd segment to remove the temporary directories from the workers.

parfor index = 1:7
    % Select value for Ts
    Ts_val = Ts_vals(index);
    
    % Change the filter time constant and simulate
    modelWorkspace = get_param("ThreeSigs","modelworkspace");
    assignin(modelWorkspace,"Ts",Ts_val)
    sim("ThreeSigs");
    
    % Create a worker run for each simulation
    workerRun(index) = Simulink.sdi.WorkerRun.getLatest
end

spmd        
    % Remove temporary directories
    cd(workDir)
    rmdir(tempDir,"s")
    rmpath(workDir)
end

Get Dataset Objects from Parallel Simulation Output

The getDataset function puts the data from a WorkerRun object into a Dataset object so you can easily post-process.

ds(7) = Simulink.SimulationData.Dataset;

for a = 1:7
    ds(a) = getDataset(workerRun(a));
end
ds(1)
ans = 
Simulink.SimulationData.Dataset '' with 3 elements

                         Name      BlockPath      
                         ________  ______________ 
    1  [1x1 Signal]      sineSig   ThreeSigs/Out1
    2  [1x1 Signal]      randSig   ThreeSigs/Out2
    3  [1x1 Signal]      chirpSig  ThreeSigs/Out3

  - Use braces { } to access, modify, or add elements using index.

Get DatasetRef Objects from Parallel Simulation Output

For big data workflows, use the getDatasetRef function to reference the data associated with the WorkerRun.

for b = 1:7
    datasetRef(b) = getDatasetRef(workerRun(b));
end
datasetRef(1)
ans = 
  DatasetRef with properties:

           Name: 'Run <run_index>: <model_name>'
            Run: [1×1 Simulink.sdi.Run]
    numElements: 3

Process Parallel Simulation Data in the Simulation Data Inspector

You can also create local Simulink.sdi.Run objects to analyze and visualize your data using the Simulation Data Inspector programmatic interface. This example shows a tag indicating the filter time constant value for each run.

for c = 1:7
    Runs(c) = getLocalRun(workerRun(c));
    Ts_val_str = num2str(Ts_vals(c));
    desc = strcat("Ts = ", Ts_val_str);
    Runs(c).Description = desc;
    Runs(c).Name = strcat("ThreeSignals run Ts=", Ts_val_str);    
end

Clean Up Worker Repositories

Clean up the files used by the workers to free up disk space for other simulations you want to run on your worker pool.

Simulink.sdi.cleanupWorkerResources

Alternatives

You can view run metadata and import data using the Simulation Data Inspector UI. For more information, see View Simulation Data in Simulation Data Inspector.

Version History

Introduced in R2012b

expand all

See Also

Objects

Functions

Topics