Simulink.sdi.enablePCTSupport

Control when to import data from parallel simulations into the Simulation Data Inspector

Syntax

Simulink.sdi.enablePCTSupport(mode)

Description

Simulink.sdi.enablePCTSupport(mode) configures data import into the Simulation Data Inspector from parallel workers according to the mode specified by mode. You can configure the Simulation Data Inspector to import only data from local workers, or data from local and remote workers. You can also set the mode to manual, which allows you to manually import runs into the Simulation Data Inspector using the Simulink.sdi.sendWorkerRunToClient function. By default, the Simulation Data Inspector is configured for the manual import mode.

Examples

Enable Automatic Data Import for All Parallel Workers

Configure Simulation Data Inspector parallel worker support to import the output automatically from both local and remote workers.

Simulink.sdi.enablePCTSupport('all')

Disable Automatic Data Import from Parallel Workers

To prevent the output from Parallel Computing Toolbox™ workers from automatically importing into the Simulation Data Inspector, specify the manual support mode.

Simulink.sdi.enablePCTSupport('manual')

Manually Send Runs from Parallel Workers to the Simulation Data Inspector

This example shows how to use Simulink.sdi.sendWorkerRunToClient to send runs created using parallel workers manually to the Simulation Data Inspector.

Setup

This example runs several simulations of the vdp model, varying the value of the gain, Mu. To set up for the parallel simulation, define a vector of Mu values and configure the Simulation Data Inspector for manual Parallel Computing Toolbox support.

% Enable manual Parallel Computing Toolbox support
Simulink.sdi.enablePCTSupport('manual');

% Choose several Mu values
MuVals = [1 2 3 4];

Initialize Parallel Workers

Use parpool (Parallel Computing Toolbox) to start a pool of four parallel workers. This example calls parpool inside an if statement so you only create a parallel pool if you don't already have one. You can use spmd (Parallel Computing Toolbox) to run initialization code common to all workers. For example, load the vdp model and select signals to log to runs that we can send to the Simulation Data Inspector on the client MATLAB. To avoid data concurrency issues when simulating with sim in parfor, create a temporary directory on each worker. After the simulations complete, another spmd block deletes the temporary directories.

p = gcp('nocreate');

if isempty(p)
    
    parpool(4);

end

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

spmd
    
    % Load system and select signals to log
    load_system('vdp')
    Simulink.sdi.markSignalForStreaming('vdp/x1',1,'on')
    Simulink.sdi.markSignalForStreaming('vdp/x2',1,'on')
    
    % Create temporary directory for simulation on worker
    workDir = pwd;
    addpath(workDir)
    tempDir = tempname;
    mkdir(tempDir)
    cd(tempDir)
    
end

Run Parallel Simulations with parfor

To stream data from parallel workers to the Simulation Data Inspector, you have to run parallel simulations using parfor (Parallel Computing Toolbox). Each worker runs a vdp simulation with a different value of Mu. Simulink cannot access the contents of the parfor loop, so the variable MuVal is defined in the worker's workspace, where the vdp model can see it, using assignin.

parfor (index = 1:4)
     
    % Set value of Mu in the worker's base workspace
    assignin('base','MuVal',MuVals(index));
    
    % Modify the value of Mu in the model and simulate
    set_param('vdp/Mu','Gain','MuVal')
    sim('vdp')
  

Access Data and Send Run to Client MATLAB

You can use the Simulation Data Inspector programmatic interface on the worker the same way you would in the client MATLAB. This example creates a Simulink.sdi.Run object and attaches the value of Mu used in the simulation with the Tag property.

    
    % Attach metadata to the run
    IDs = Simulink.sdi.getAllRunIDs;
    lastIndex = length(IDs);
    runID = Simulink.sdi.getRunIDByIndex(lastIndex);
    parRun = Simulink.sdi.getRun(runID);
    parRun.Tag = strcat('Mu = ',num2str(MuVals(index)));
    
    % Send the run to the Simulation Data Inspector on the client MATLAB
    Simulink.sdi.sendWorkerRunToClient
    
end

Close Temporary Directories and View Runs in the Simulation Data Inspector

Use another spmd section to delete the temporary directories created on the workers once the simulations complete. In each simulation, Simulink.sdi.sendWorkerRunToClient imported runs from all the workers into the Simulation Data Inspector. You can view the data and check the run properties to see the value of Mu used during simulation.

spmd

    % Remove temporary directories
    cd(workDir)
    rmdir(tempDir, 's')
    rmpath(workDir)

end

Simulink.sdi.view

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

Input Arguments

mode — Parallel worker data import mode

'manual' (default) | 'local' | 'all'

Simulation Data Inspector data import mode for data logged on parallel workers, specified as one of these options:

• 'manual' — Do not automatically import runs created on parallel workers. You can manually import runs created on parallel workers using the Simulink.sdi.sendWorkerRunToClient function.

• 'local' — Automatically import runs created on local workers.

• 'all' — Automatically import runs created on local and remote workers.

Data Types: char | string

Alternative Functionality

You can modify the parallel computing support mode in the Simulation Data Inspector by selecting Preferences > Parallel.

Compatibility Considerations

'none' input is no longer supported

Errors starting in R2020a

Starting in R2020a, the Simulink.sdi.enablePCTSupport function no longer supports the 'none' input option. To disable automatic import of data logged on parallel workers into the Simulation Data Inspector, use the 'manual' option.

Logical inputs are ignored

Behavior changed in R2020a

Starting in R2020a, the Simulink.sdi.enablePCTSupport function ignores logical inputs. In scripts that specify a logical input for the Simulink.sdi.enablePCTSupport function, replace a 0 or false input with the 'manual' input option and a 1 or true input with the 'all' option to achieve equivalent behavior.

Input values have changed

Behavior changed in R2018a

Starting in R2018a, the Simulink.sdi.enablePCTSupport input values changed to:

• 'local'

• 'none'

• 'all'

• 'manual'

In R2017b, the Simulink.sdi.enablePCTSupport function accepted a logical input to enable or disable Simulation Data Inspector support for data logged in parallel simulations.

• true or 1 enables support for automatically importing data from all parallel workers into the Simulation Data Inspector.

  In R2018a, use the 'all' option for the same behavior. You can also use the new 'local' input when you want to automatically import data only from local workers.

• false or 0 disables all support for importing data logged on parallel workers.

  In R2018a, use the 'none' option for the same behavior. You can also use the new 'manual' option when you want to analyze data on the worker to determine whether you want to import individual runs into the Simulation Data Inspector from a parallel worker.