Run Test-Case Sweep Using Parallel Simulations

This example uses:

Open Live Script

This example shows how to run multiple Simulink® simulations corresponding to different test cases using batchsim and Parallel Computing Toolbox™. The batchsim function offloads simulations to a compute cluster, freeing up your local machine so you can continue working while the batch job is processing. While parsim is useful for running parallel simulations on local resources, batchsim is useful for running a large number of computationally expensive simulations. If you do not have Parallel Computing Toolbox, the simulations in this example will run serially.

Explore Model

The sldemo_suspn_3dof model simulates vehicle dynamics based on the interaction between the road and the vehicle suspension for different road profiles. The model captures vehicle dynamics in three degrees of freedom: vertical displacement, roll, and pitch. The Signal Editor block named Road Profiles stores measured road profile data for the left and right tires as different test cases. The Road-Suspension Interaction subsystem calculates the suspension forces on the vehicle at the four tire locations based on the road data and the current vehicle state. The Body Dynamics subsystem uses these forces and the resulting pitch and roll moments to calculate the vehicle motion in each of the three degrees of freedom.

mdl = "sldemo_suspn_3dof";
open_system(mdl);

The sldemo_suspn_3dof model

To log the vertical vehicle displacement, the signal connected to the Vertical disp output port of the Body Dynamics subsystem is marked for signal logging, as indicated by the logging badge. To examine the logging settings, right-click the signal and select Properties. In the Signal Properties dialog box, the Log signal data parameter is selected and the signal is configured to log data using the custom logging name vertical_disp. For more information, see Save Signal Data Using Signal Logging.

Prepare Parameter Inputs

To determine if the design meets desired performance goals, simulate the model using different road profiles and examine the vertical vehicle displacement over time. The Signal Editor block named Road Profiles contains data for multiple road condition scenarios. Read the number of test cases from the NumberOfScenarios parameter of the Road Profiles block.

sigEditBlk = mdl+"/Road Profiles";
numCases = str2double(get_param(sigEditBlk,"NumberOfScenarios"));

Use the number of cases to determine the number of simulations to run. To define the set of simulations to run, preallocate an array of Simulink.SimulationInput objects for the model, one per simulation. Prepare to run one simulation per test case. 

in(1:numCases) = Simulink.SimulationInput(mdl);

The Road Profiles block uses a mask to provide a customized dialog box. The mask parameter ActiveScenario specifies the sweep value for the Signal Editor block scenario. Use a for loop to set the active scenario for each simulation.

for idx = 1:numCases
    in(idx) = in(idx).setBlockParameter(sigEditBlk,"ActiveScenario", idx);
end

Specifying the block parameter on the SimulationInput object does not apply it to the model immediately. The software applies the specified value during simulation and reverts back to the original value, if possible, after the simulation finishes.

Run Parallel Simulations Using batchsim

Run a batch simulation job to run parallel simulations on three workers. To create a pool of size n with batchsim, your cluster must have at least n + 1 workers: One worker manages the job and the other n workers run the simulations. Running a batch simulation job returns a Simulink.Simulation.Job object. Use the Job object to monitor the status of a batch job, fetch outputs of a completed batch job, or cancel one or more jobs. To access the job object later from any machine with access to the cluster, use the job ID contained in the object metadata. Wait for the job to finish, and then display the diary of the job. 

simJob = batchsim(in,Pool=3);
wait(simJob) 
diary(simJob)
--- Start Diary ---
[29-Jan-2026 15:15:54] Checking for availability of parallel pool...
[29-Jan-2026 15:15:55] Starting Simulink on parallel workers...
[29-Jan-2026 15:16:43] Configuring simulation cache folder on parallel workers...
[29-Jan-2026 15:16:43] Loading model on parallel workers...
[29-Jan-2026 15:17:02] Running simulations...
[29-Jan-2026 15:17:23] Completed 1 of 20 simulation runs
[29-Jan-2026 15:17:23] Received simulation output (size: 3.06 MB) for run 1 from parallel worker.
[29-Jan-2026 15:17:23] Completed 2 of 20 simulation runs
[29-Jan-2026 15:17:23] Received simulation output (size: 3.06 MB) for run 2 from parallel worker.
[29-Jan-2026 15:17:23] Completed 3 of 20 simulation runs
[29-Jan-2026 15:17:23] Received simulation output (size: 3.06 MB) for run 3 from parallel worker.
[29-Jan-2026 15:17:26] Completed 4 of 20 simulation runs
[29-Jan-2026 15:17:26] Received simulation output (size: 3.06 MB) for run 4 from parallel worker.
[29-Jan-2026 15:17:26] Completed 5 of 20 simulation runs
[29-Jan-2026 15:17:26] Received simulation output (size: 3.06 MB) for run 5 from parallel worker.
[29-Jan-2026 15:17:26] Completed 6 of 20 simulation runs
[29-Jan-2026 15:17:26] Received simulation output (size: 3.06 MB) for run 6 from parallel worker.
[29-Jan-2026 15:17:31] Completed 7 of 20 simulation runs
[29-Jan-2026 15:17:31] Received simulation output (size: 3.06 MB) for run 7 from parallel worker.
[29-Jan-2026 15:17:31] Completed 8 of 20 simulation runs
[29-Jan-2026 15:17:31] Received simulation output (size: 3.06 MB) for run 8 from parallel worker.
[29-Jan-2026 15:17:31] Completed 9 of 20 simulation runs
[29-Jan-2026 15:17:31] Received simulation output (size: 3.06 MB) for run 9 from parallel worker.
[29-Jan-2026 15:17:34] Completed 10 of 20 simulation runs
[29-Jan-2026 15:17:34] Received simulation output (size: 3.06 MB) for run 10 from parallel worker.
[29-Jan-2026 15:17:34] Completed 11 of 20 simulation runs
[29-Jan-2026 15:17:34] Received simulation output (size: 3.06 MB) for run 11 from parallel worker.
[29-Jan-2026 15:17:34] Completed 12 of 20 simulation runs
[29-Jan-2026 15:17:34] Received simulation output (size: 3.06 MB) for run 12 from parallel worker.
[29-Jan-2026 15:17:37] Completed 13 of 20 simulation runs
[29-Jan-2026 15:17:37] Received simulation output (size: 3.06 MB) for run 13 from parallel worker.
[29-Jan-2026 15:17:37] Completed 14 of 20 simulation runs
[29-Jan-2026 15:17:37] Received simulation output (size: 3.06 MB) for run 14 from parallel worker.
[29-Jan-2026 15:17:37] Completed 15 of 20 simulation runs
[29-Jan-2026 15:17:37] Received simulation output (size: 3.06 MB) for run 15 from parallel worker.
[29-Jan-2026 15:17:41] Completed 16 of 20 simulation runs
[29-Jan-2026 15:17:41] Received simulation output (size: 3.06 MB) for run 16 from parallel worker.
[29-Jan-2026 15:17:41] Completed 17 of 20 simulation runs
[29-Jan-2026 15:17:41] Received simulation output (size: 3.06 MB) for run 17 from parallel worker.
[29-Jan-2026 15:17:41] Completed 18 of 20 simulation runs
[29-Jan-2026 15:17:41] Received simulation output (size: 3.06 MB) for run 18 from parallel worker.
[29-Jan-2026 15:17:44] Completed 19 of 20 simulation runs
[29-Jan-2026 15:17:44] Received simulation output (size: 3.06 MB) for run 19 from parallel worker.
[29-Jan-2026 15:17:44] Completed 20 of 20 simulation runs
[29-Jan-2026 15:17:44] Received simulation output (size: 3.06 MB) for run 20 from parallel worker.
[29-Jan-2026 15:17:44] Cleaning up parallel workers...

--- End Diary ---

Fetch Outputs

Access the results of the batch job using fetchOutputs. The fetchOutputs function retrieves the results from the workers and returns an array of Simulink.SimulationOutput objects.

out = fetchOutputs(simJob)
out = 
1x20 Simulink.SimulationOutput array

Plot Results

To see how the vehicle performed in different road profiles, plot the vertical vehicle displacement for the different simulations.

  1. Access the SimulationOutput object for each simulation. The SimulationOutput object contains a property for each type of logged data.

  2. Access the logged signal data using dot notation. Within each SimulationOutput object, signal logging data and metadata are grouped in a Simulink.SimulationData.Dataset object with the default name of logsout.

  3. Access the vertical_disp signal using get.

  4. Access the timeseries object that contains the time and signal data for vertical_disp using the Values property of the vertical_disp signal.

  5. Plot the results for each simulation.

legend_labels = cell(1,numCases);
for idx = numCases:-1:1
    simOut = out(idx);
    sigLoggingData = simOut.logsout;
    sig = get(sigLoggingData,"vertical_disp");
    ts = sig.Values;

plot(ts);
    legend_labels{idx} = "Run "+num2str(idx);         
    hold on
end
title("Response of a 3-DoF Suspension Model")
xlabel("Time (s)");
ylabel("Vehicle vertical displacement (m)");
legend(legend_labels,"Location","NorthEastOutside");

Figure contains an axes object. The axes object with title Response of a 3-DoF Suspension Model, xlabel Time (s), ylabel Vehicle vertical displacement (m) contains 20 objects of type line. These objects represent Run 1, Run 2, Run 3, Run 4, Run 5, Run 6, Run 7, Run 8, Run 9, Run 10, Run 11, Run 12, Run 13, Run 14, Run 15, Run 16, Run 17, Run 18, Run 19, Run 20.

Close MATLAB Workers

Close the parallel pool.

delete(gcp("nocreate"));

See Also

| | |

Topics