Simulink.sdi.Run

Access run signals and metadata

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:

• When you want to access a run that corresponds to a specific run ID, use the Simulink.sdi.getRun function.

  Tip

  Use the Simulink.sdi.getAllRunIDs function to get the run IDs for all the runs in the Simulation Data Inspector.

• When you want to access the most recently created run in the Simulation Data Inspector, use the Simulink.sdi.Run.getLatest function.

• When you want to access the run that corresponds to the in-progress or most recently completed simulation of a model, use the Simulink.sdi.getCurrentSimulationRun function.

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

ID — Run ID

integer

This property is read-only.

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

Name — Run name

character vector | string

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'

Description — Run description

[] (default) | character vector | string

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 — Information tag

[] (default) | character vector | string

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'

DateCreated — Run creation timestamp

datetime object

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

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

Data Types: datetime

RunIndex — Index of run in Simulation Data Inspector

integer

This property is read-only.

Index of the run in the Simulation Data Inspector when the run was created, returned 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.

SignalCount — Number of signals in run

integer

This property is read-only.

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

Model — Model simulated to create run

character vector

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.

SimMode — Simulation mode

character vector

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.

StartTime — Run start time

scalar

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

StopTime — Run stop time

scalar

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

SLVersion — Software version used for model simulation that created run

character vector

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.

ModelVersion — Version of model simulated to create run

character vector

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.

UserID — System account

character vector

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.

MachineName — Name of machine used for simulation

character vector

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.

Platform — Operating system on machine used for simulation

character vector

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'

TaskName — Task name

[] (default) | character vector

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.

SolverType — Type of solver used in simulation that created run

'Variable-Step' | 'Fixed-Step'

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.

SolverName — Name of solver used in simulation that created run

character vector

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

SolverStepSize — Solver step size used in simulation

character vector

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'

Status — Simulation status

character vector

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.

StopEventSource — Block that issued stop event

Simulink.SimulationData.BlockPath

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

StopEventDescription — Translated description of simulation stop

character vector

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'

ExecutionErrors — Errors that occurred during simulation

character vector

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

ExecutionWarnings — Warnings that occurred during simulation

character vector

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

ModelInitializationTime — Time to initialize model for simulation that created run

double

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.

ModelExecutionTime — Execution time for simulation that created run

double

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.

ModelTerminationTime — Time to terminate simulation that created run

double

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.

ModelTotalElapsedTime — Total simulation time for simulation that created run

double

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.

UserString — User-specified string

character vector

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.

Object Functions

add	Import data into existing run in Simulation Data Inspector using Simulink.sdi.Run object
export	Export run to base workspace or file
getAllSignalIDs	Get all signal IDs for signals in Simulink.sdi.Run object
getAllSignals	Get all signals in Simulink.sdi.Run object
getDatasetRef	Create a Simulink.sdi.DatasetRef object for a run
getSignalByIndex	Get signal in Simulink.sdi.Run object by index
getSignalIDByIndex	Get signal ID for signal at specified index in Simulink.sdi.Run object
getSignalIDsByName	Get signal IDs for signals inside Simulink.sdi.Run object using signal name
getSignalsByName	Access signals in a Simulink.sdi.Run object using signal name
isValidSignalID	Check whether signal ID corresponds to signal in Simulink.sdi.Run object

Examples

Plot Signals from Simulation Run

This example demonstrates how to access the Simulink.sdi.Run object for a Simulation Data Inspector run created by logging signals. From the Simulink.sdi.Run object you can get Simulink.sdi.Signal objects that contain the logged signal data and metadata. You can use the Signal objects and the plotOnSubPlot function to plot the data in the Simulation Data Inspector.

Create a Simulation Run and Access the Run Object

The ex_vdp model logs two signals. To create a simulation run containing the logged data, simulate the model.

sim('ex_vdp');

The Simulation Data Inspector keeps track of runs by assigning a unique numeric run ID to each run created by simulation, importing data, or opening a session. To access the run object for the simulation you just performed, use the Simulink.sdi.getAllRunIDs function and take the last run ID in the returned vector.

runIDs = Simulink.sdi.getAllRunIDs;
runID = runIDs(end);

Once you have the run ID for the run, you can use the Simulink.sdi.getRun function to get the Simulink.sdi.Run object that corresponds to the run. You can use the Run object to check the metadata associated with the run, including the number of signals in the run.

vdpRun = Simulink.sdi.getRun(runID);

vdpRun.SignalCount

ans = int32
    2

Plot Data Using Signal Objects

Use the getSignalByIndex function to access signals from the Run object, vdpRun.

signal1 = getSignalByIndex(vdpRun,1);
signal2 = getSignalByIndex(vdpRun,2);

Use the Simulink.sdi.setSubPlotLayout function to specify a 2-by-1 layout.

Simulink.sdi.setSubPlotLayout(2,1)

Before plotting the data, use the Simulink.sdi.clearAllSubPlots function to clear any data that is already plotted.

Simulink.sdi.clearAllSubPlots

Plot one signal on each subplot. To plot signals on the first subplot, you can set the checked property for the signal. To plot signals on subplots other than the first subplot, use the plotOnSubPlot function.

signal1.Checked = true;
plotOnSubPlot(signal2,2,1,true);

View the Plotted Data

To view the plots you just created, open the Simulation Data Inspector using the Simulink.sdi.view function.

Create a Run and View the Data

This example shows how to create a run, add data to it, and then view the data in the Simulation Data Inspector.

Create Data for the Run

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

time = linspace(0,20,100);

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 a Run and Add Data

Use the Simulink.sdi.view function to open the Simulation Data Inspector.

Simulink.sdi.view

To import data into the Simulation Data Inspector from the workspace, create a Simulink.sdi.Run object using the Simulink.sdi.Run.create function. Add information about the run to its metadata 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';

Use the add function to add the data you created in the workspace to the empty run.

add(sinusoidsRun,'vars',sine_ts,cos_ts);

Plot the Data in the Simulation Data Inspector

Use the getSignalByIndex function to access Simulink.sdi.Signal objects that contain the signal data. You can use the Simulink.sdi.Signal object properties to specify the line style and color for the signal and plot it in the Simulation Data Inspector. 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 = [0 1 0];
cos_sig.LineDashed = '--';

Use the Simulink.sdi.setSubPlotLayout function to configure a 2-by-1 subplot layout in the Simulation Data Inspector plotting area. Then use the plotOnSubplot function to plot the sine signal on the top subplot and the cosine signal on the lower subplot.

Simulink.sdi.setSubPlotLayout(2,1);

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

Close the Simulation Data Inspector and Save Your Data

When you have finished 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')

Access Data from a Parallel Simulation

This example executes parallel simulations of the model slexAircraftExample with different input filter time constants and shows several ways to access the data using the Simulation Data Inspector programmatic interface.

Setup

Start by ensuring the Simulation Data Inspector is empty and 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.

% Make sure the Simulation Data Inspector is empty, and PCT support is
% enabled. 
Simulink.sdi.clear
Simulink.sdi.enablePCTSupport('local')

% Define Ts values
Ts_vals = [0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1]; 

Initialize Parallel Workers

Use gcp 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 slexAircraftExample 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;

Starting parallel pool (parpool) using the 'local' profile ...
connected to 4 workers.

spmd
    
    % Load system and select signals to log
    load_system('slexAircraftExample')
    Simulink.sdi.markSignalForStreaming('slexAircraftExample/Pilot', 1, 'on')
    Simulink.sdi.markSignalForStreaming('slexAircraftExample/Aircraft Dynamics Model', 4, 'on')
    
    % Create temporary directory on each worker
    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('slexAircraftExample','modelworkspace');
    modelWorkspace.assignin('Ts',Ts_val)
    sim('slexAircraftExample')
    
    % 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 method puts the data from a WorkerRun into a Dataset object so you can easily post-process.

ds(7) = Simulink.SimulationData.Dataset;

for a = 1:7
    ds(a) = workerRun(a).getDataset;
end
ds(1)

ans = 
Simulink.SimulationData.Dataset '' with 2 elements

                         Name        BlockPath                                
                         __________  ________________________________________ 
    1  [1x1 Signal]      alpha, rad  ...rcraftExample/Aircraft Dynamics Model
    2  [1x1 Signal]      Stick       slexAircraftExample/Pilot               

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

Get DatasetRef Objects from Parallel Simulation Output

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

for b = 1:7
    datasetRef(b) = workerRun(b).getDatasetRef;
end

datasetRef(1)

ans = 
  DatasetRef with properties:

           Name: 'Run 3: slexAircraftExample'
            Run: [1×1 Simulink.sdi.Run]
    numElements: 2

Process Parallel Simulation Data in the Simulation Data Inspector

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

for c = 1:7
    
    Runs(c) = workerRun(c).getLocalRun;
    Ts_val_str = num2str(Ts_vals(c));
    desc = strcat('Ts = ', Ts_val_str);
    Runs(c).Description = desc;
    Runs(c).Name = strcat('slexAircraftExample 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 Data in the Simulation Data Inspector.

Version History

Introduced in R2012b