Simulink.sdi.Run class

Package: Simulink.sdi

Access run signals and metadata

Description

The Simulink.sdi.Run object manages a run's metadata and the signals that comprise the run. You can use several methods to retrieve Simulink.sdi.Signal objects to access the signal data and metadata.

Construction

runObj = Simulink.sdi.Run.create creates an empty Simulink.sdi.Run object.

runObj = Simulink.sdi.getRun(runID) creates a Simulink.sdi.Runobject, runObj, for the run corresponding to runID.

You can also use the Simulink.sdi.createRun and Simulink.sdi.createRunOrAddToStreamedRun functions to create Run objects.

Input Arguments

expand all

Unique number identifying the run.

Properties

expand all

Unique numerical identification for the run.

Name of the run. By default, name is empty.

Example: 'Run 1'

Description of the run. By default, Description is empty.

Example: 'Initial simulation'

Tag for additional run information. By default, Tag is empty. You can use the Tag parameter to categorize your simulation data or attach extra information to simulation runs.

Example: 'Gain = 2'

Date and time the run was created.

Data Types: datetime

Number of signals contained in the run.

Name of the model that created the run.

Simulation mode used to create the run, for runs created by simulation.

First time point shared by all signals in the run.

Last time point shared by all signals in the run.

Version of Simulink® used for the simulation that created the run.

Version of the model simulated to create the run, taken from the Model Properties.

System account used for the simulation that created the run. UserID only has a value for runs produced with Simulink simulations.

Name of the machine used for the simulation that created the run. MachineName only has a value for runs produced with Simulink simulations.

Name of the simulation task that created the run for runs created with Parallel Computing Toolbox™ workers.

The type of solver used for the simulation that created the run. SolverType only has a value for runs produced with Simulink simulations.

Name of the solver used for the simulation that created the run. SolverName only has a value for runs produced with Simulink simulations.

Example: ode45

Amount of time to initialize the model for the simulation that created the run. ModelInitializationTime only has a value for runs produced with Simulink simulations.

Execution time of the model simulation that created the run. ModelExecutionTime only has a value for runs produced with Simulink simulations.

Time to terminate the simulation that created the run. ModelTerminationTime only has a value for runs produced with Simulink simulations.

Total time to run model simulation that created the run. ModelTotalElapsedTime only has a value for runs produced with Simulink simulations.

Methods

addAdd signals to run
createCreate a Simulink.sdi.Run object
exportExport run to base workspace or a file
getDatasetRefCreate a Simulink.sdi.DatasetRef object for a run
getSignalByIndexGet Simulink.sdi.Signal object by index
getSignalIDByIndexReturn signal ID for signal at index
isValidSignalIDDetermine whether signal ID is valid within a run

Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects (MATLAB).

Examples

collapse all

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 you can use to plot the data.

Create a Simulation Run and Access the Run Object

The sldemo_fuelsys model includes several signals that are marked for logging. 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 each run created by simulation, importing data, or opening a session a unique numeric ID. To access the run object for the simulation 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 of interest, you can use the Simulink.sdi.getRun function to get the Simulink.sdi.Run object corresponding to the run. You can use the Run object to check 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 of interest from the Run object, fuelRun.

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

Use the Simulink.sdi.setSubPlotLayout function to specify a 3-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.

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

This example creates timeseries objects for a sine and a cosine. To visualize your data, the Simulation Data Inspector requires at least a time vector that corresponds with your data.

% Generate timeseries data
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 Simulation Data Inspector Run and Add Your Data

To give the Simulation Data Inspector access to your data, use the create method and create a run. This example modifies some of the run's properties to help identify the data. You can easily view run and signal properties with the Simulation Data Inspector.

% Create a run
sinusoidsRun = Simulink.sdi.Run.create;
sinusoidsRun.Name = 'Sinusoids';
sinusoidsRun.Description = 'Sine and cosine signals with different frequencies';

% Add timeseries data to run
sinusoidsRun.add('vars', sine_ts, cos_ts);

Plot Your Data Using the Simulink.sdi.Signal Object

The getSignalByIndex method returns a Simulink.sdi.Signal object that can be used to plot the signal in the Simulation Data Inspector. You can also programmatically control aspects of the plot's appearance, such as the color and style of the line representing the signal. This example customizes the subplot layout and signal characteristics.

% Get signal, modify its properties, and change Checked property to true
sine_sig = sinusoidsRun.getSignalByIndex(1);
sine_sig.LineColor = [0 0 1];
sine_sig.LineDashed = '-.';
sine_sig.Checked = true;

% Add another subplot for the cosine signal
Simulink.sdi.setSubPlotLayout(2, 1);

% Plot the cosine signal and customize its appearance
cos_sig = sinusoidsRun.getSignalByIndex(2);
cos_sig.LineColor = [0 1 0];
cos_sig.plotOnSubPlot(2, 1, true);

% View the signal in the Simulation Data Inspector
Simulink.sdi.view

Close the Simulation Data Inspector and Save Your Data

Simulink.sdi.close('sinusoids.mat')

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 runs and their properties in the Simulation Data Inspector UI. You can also import data to create runs in the Simulation Data Inspector GUI. For more information, see View Data with the Simulation Data Inspector.

Introduced in R2012b