Stream Data from MAT File as Input for Parallel Simulations

This example shows how to use Simulink.SimulationData.DatasetRef objects and the parsim function to stream input data from a version 7.3 MAT file for parallel simulations. Consider following the steps outlined in this example when the inputs for your simulation are too large to load into memory. For example, you can use data logged to persistent storage from one set of parallel simulations as input for another.

This example uses parsim to run multiple simulations of a model, with each simulation using unique input data. The model is based on the model sldemo_suspn_3dof, which is used in the example Multiple Simulations Workflow Tips. The model for this example is modified to use Inport blocks as the source for inputs instead of the Signal Editor block. The model simulates the response of a suspension system to different road conditions. The MAT file used in this example contains multiple Simulink.SimulationData.Dataset objects that each represent various road conditions. The example uses DatasetRef objects to stream the contents of an entire referenced Dataset object as simulation input.

You can also stream data for individual signals into parallel simulations run with parsim using matlab.io.datastore.SimulationDatastore objects. For more information, see Stream Individual Signals Using SimulationDatastore Objects.

Open Model and Access Input Data

Open the model ex_sldemo_suspn_3dof_parsim_stream. The model has two top-level input ports that load external input data. Each Dataset object used as simulation input contains two elements: one for each input port.

mdl = "ex_sldemo_suspn_3dof_parsim_stream";
open_system(mdl)

To determine the contents of the MAT file without loading the data into memory, use the Simulink.SimulationData.DatasetRef.getDatasetVariableNames function. The function returns a cell array that contains an element for the name of each variable in the MAT file that contains a Dataset object.

f = "suspn_3dof_test_cases.mat";
vars = Simulink.SimulationData.DatasetRef.getDatasetVariableNames(f);
numCases = numel(vars);

Use DatasetRef objects to stream the test case data into the model during simulation. A DatasetRef object references a Dataset object in a MAT file. During simulation, the software streams input data from the file by incrementally loading data from the Dataset object the DatasetRef object references.

Preallocate an array of DatasetRef objects that has an element for each variable in the MAT file that contains a Dataset object. Then, create a DatasetRef object to reference each of these variables.

inData(1:numCases) = Simulink.SimulationData.DatasetRef(f,vars{1});
for k = 1:numCases
    inData(k) = Simulink.SimulationData.DatasetRef(f,vars{k});
end

Configure and Run Parallel Simulations

To use the set of test case inputs as input for a set of parallel simulations, create an array of Simulink.SimulationInput objects to configure each simulation. Then, use the setExternalInput function to specify the test case to stream as input for each simulation.

simin(1:numCases) = Simulink.SimulationInput(mdl);
for n = 1:numCases
    simin(n) = setExternalInput(simin(n),inData(n));
end

To run the simulations in parallel using the parsim function, you must have the Parallel Computing Toolbox™. Without the Parallel Computing Toolbox, the parsim function runs the simulations in serial.

To run simulations in parallel, the parsim function creates a worker pool. By default, parsim uses a local pool. All workers in the local pool have access to the MAT file used to create the DatasetRef objects.

If you use remote workers, you can send the MAT file to each worker by using the AttachedFiles name-value argument. Sending a copy of the file to each remote worker can take time, especially for large files. When you stream input data from a MAT-file for parallel simulations that use remote workers, consider storing the MAT file in a location that all workers can access and creating DatasetRef objects that reference that copy of the file.

Run the simulations using the parsim function.

out = parsim(simin);

[30-Sep-2024 13:27:44] Checking for availability of parallel pool...
Starting parallel pool (parpool) using the 'Processes' profile ...
30-Sep-2024 13:28:50: Job Queued. Waiting for parallel pool job with ID 5 to start ...
30-Sep-2024 13:29:51: Job Running. Waiting for parallel pool workers to connect ...
Connected to parallel pool with 8 workers.
[30-Sep-2024 13:30:14] Starting Simulink on parallel workers...
[30-Sep-2024 13:31:07] Configuring simulation cache folder on parallel workers...
[30-Sep-2024 13:31:08] Loading model on parallel workers...
[30-Sep-2024 13:31:17] Running simulations...
[30-Sep-2024 13:31:32] Completed 1 of 20 simulation runs
[30-Sep-2024 13:31:32] Received simulation output (size: 3.06 MB) for run 1 from parallel worker.
[30-Sep-2024 13:31:33] Completed 2 of 20 simulation runs
[30-Sep-2024 13:31:33] Received simulation output (size: 3.06 MB) for run 2 from parallel worker.
[30-Sep-2024 13:31:33] Completed 3 of 20 simulation runs
[30-Sep-2024 13:31:33] Received simulation output (size: 3.06 MB) for run 3 from parallel worker.
[30-Sep-2024 13:31:33] Completed 4 of 20 simulation runs
[30-Sep-2024 13:31:33] Received simulation output (size: 3.06 MB) for run 4 from parallel worker.
[30-Sep-2024 13:31:33] Completed 5 of 20 simulation runs
[30-Sep-2024 13:31:33] Received simulation output (size: 3.06 MB) for run 5 from parallel worker.
[30-Sep-2024 13:31:33] Completed 6 of 20 simulation runs
[30-Sep-2024 13:31:33] Received simulation output (size: 3.06 MB) for run 6 from parallel worker.
[30-Sep-2024 13:31:33] Completed 7 of 20 simulation runs
[30-Sep-2024 13:31:33] Received simulation output (size: 3.06 MB) for run 7 from parallel worker.
[30-Sep-2024 13:31:33] Completed 8 of 20 simulation runs
[30-Sep-2024 13:31:33] Received simulation output (size: 3.06 MB) for run 8 from parallel worker.
[30-Sep-2024 13:31:36] Completed 9 of 20 simulation runs
[30-Sep-2024 13:31:36] Received simulation output (size: 3.06 MB) for run 9 from parallel worker.
[30-Sep-2024 13:31:36] Completed 10 of 20 simulation runs
[30-Sep-2024 13:31:36] Received simulation output (size: 3.06 MB) for run 10 from parallel worker.
[30-Sep-2024 13:31:36] Completed 11 of 20 simulation runs
[30-Sep-2024 13:31:36] Received simulation output (size: 3.06 MB) for run 11 from parallel worker.
[30-Sep-2024 13:31:36] Completed 12 of 20 simulation runs
[30-Sep-2024 13:31:36] Received simulation output (size: 3.06 MB) for run 12 from parallel worker.
[30-Sep-2024 13:31:36] Completed 13 of 20 simulation runs
[30-Sep-2024 13:31:36] Received simulation output (size: 3.06 MB) for run 13 from parallel worker.
[30-Sep-2024 13:31:36] Completed 14 of 20 simulation runs
[30-Sep-2024 13:31:36] Received simulation output (size: 3.06 MB) for run 14 from parallel worker.
[30-Sep-2024 13:31:36] Completed 15 of 20 simulation runs
[30-Sep-2024 13:31:36] Received simulation output (size: 3.06 MB) for run 15 from parallel worker.
[30-Sep-2024 13:31:36] Completed 16 of 20 simulation runs
[30-Sep-2024 13:31:36] Received simulation output (size: 3.06 MB) for run 16 from parallel worker.
[30-Sep-2024 13:31:40] Completed 17 of 20 simulation runs
[30-Sep-2024 13:31:40] Received simulation output (size: 3.06 MB) for run 17 from parallel worker.
[30-Sep-2024 13:31:40] Completed 18 of 20 simulation runs
[30-Sep-2024 13:31:40] Received simulation output (size: 3.06 MB) for run 18 from parallel worker.
[30-Sep-2024 13:31:40] Completed 19 of 20 simulation runs
[30-Sep-2024 13:31:40] Received simulation output (size: 3.06 MB) for run 19 from parallel worker.
[30-Sep-2024 13:31:40] Completed 20 of 20 simulation runs
[30-Sep-2024 13:31:40] Received simulation output (size: 3.06 MB) for run 20 from parallel worker.
[30-Sep-2024 13:31:40] Cleaning up parallel workers...

View Simulation Results

Create a plot of the vertical displacement for the vehicle for all the road profile test cases that simulated without error.

if isempty(out(1).ErrorMessage)
    legendLabels = cell(1,numCases);
    for m = 1:numCases
        if isempty(out(m).ErrorMessage)
            simout = out(m);
            logsout = simout.logsout;
            ts = get(logsout,"vertical_disp").Values;
            plot(ts);
            legendLabels{m} = ['Run ' num2str(m)]; 
        end
            hold on
    end
    title("Response of a 3-DoF Suspension Model")
    xlabel("Time (s)");
    ylabel("Vehicle vertical displacement (m)");
    legend(legendLabels,Location="NorthEastOutside");
end

You can also view parsim simulation results using the Simulation Manager. To view results in the Simulation Manager, use the ShowSimulationManager name-value argument for parsim. With the Simulation Manager, you can monitor the progress of the runs, view simulation data, and show the parsim results in the Simulation Data Inspector.

Close Parallel Workers

When you have finished running parallel simulations, you can close the worker pool using this command or wait for the worker pool to close automatically.

delete(gcp("nocreate"))

Parallel pool using the 'Processes' profile is shutting down.