Documentation

Parallel Simulations Using Parsim: Parameter Sweep in Rapid Accelerator Mode

This example shows how to run multiple simulations of a Monte Carlo study in parallel by using Parallel Computing Toolbox™. Parallel execution leverages the multiple cores of your host machine to run many simulations more quickly. These simulations could also be run in parallel on computer clusters using the MATLAB Distributed Computing Server™. This example will work even if the Parallel Computing Toolbox™ or the MATLAB Distributed Computing Server™ is not available, but the simulations will run in serial.

Explore Example Model

The model sldemo_suspn_3dof simulates vehicle dynamics based on the interaction between road and suspension for different road profiles. The model captures vehicle dynamics in three degrees of freedom: vertical displacement, roll, and pitch. The Signal Builder block stores measured road profile data for the left and right tires as different test groups. 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.

In this Monte Carlo study, the vehicle mass is varied to study its effect on the vehicle dynamics. Parallel Computing Toolbox is used to speed up these multiple simulations, as illustrated below.

mdl = 'sldemo_suspn_3dof';
isModelOpen = bdIsLoaded(mdl);
open_system(mdl);

Setup to Build the Rapid Accelerator Target

The Rapid Accelerator executable for the model is build in the SetupFcn call using the buildRapidAcceleratorTarget function from the Simulink.BlockDiagram package. The buildRapidAcceleratorTarget function returns the default run-time parameter set which is assigned to a global variable, RTP, in the SetupFcn and is used in the next step to modify the parameter values. Open sldemo_parsim_paramsweep_suspn_raccel_setup in the editor to inspect the code. Note that the build process is optimized so that if the build files are already present and compatible with the model and machine architecture then it returns early.

Set up Multiple Simulations Using SimulationInput Objects

Store the sweep values in a variable, Mb_sweep, in the base workspace.

Mb_sweep = Mb*(0.5:5:45.5);

Determine the number of simulations to run, which is equal to the number of sweep values. Store the number in a variable, numSims.

numSims = length(Mb_sweep);

Use a for loop to:

  1. Create Simulink.SimulationInput objects for the model. Create one object per simulation. Store the objects as an array in a variable, in.

  2. Specify the model parameters on the SimulationInput object.

for i = numSims:-1:1
    in(i) = Simulink.SimulationInput(mdl);
    in(i) = in(i).setModelParameter('SimulationMode', 'rapid', ...
        'RapidAcceleratorUpToDateCheck', 'off');
    in(i).PreSimFcn = @(x) sldemo_parsim_paramsweep_suspn_raccel_presim(x, Mb_sweep(i));
end

The SimulationInput object is used to modify the model parameters. 'SimulationMode' is set to use rapid accelerator and 'RapidAcceleratorUpToDateCheck' model parameter is set to 'off' to skip up-to-date checks since there are no structural changes made to the model between simulations and the same build files can be used. Note that specifying the model parameter on the SimulationInput object does not apply it to the model immediately. The specified value will be applied during the simulation and reverted back to its original value, if possible, after the simulation finishes. Inspect the code in the PreSimFcn, sldemo_parsim_paramsweep_suspn_raccel_presim. It uses modifyTunableParameters from the Simulink.BlockDiagram package to change the parameter corresponding to vehicle mass. The first argument to the PreSimFcn is always the SimulationInput object, and is passed into the function by Simulink®. The PreSimFunction adds another model parameter to the SimulationInput object and returns it to be used for simulation.

Run Simulations in Parallel Using Parsim

Use the parsim function to execute the simulations in parallel. The array of SimulationInput objects, in, created in the last step is passed into the parsim function as the first argument. The output from the parsim command is an array of Simulink.SimulationOutput objects which is stored in the variable out. Set the 'ShowProgress' option to 'on' to print a progress of the simulations on the MATLAB command window. As mentioned earlier, the SetupFcn is passed as a parameter to the parsim command to build the rapid accelerator target on the workers if required.

out = parsim(in, 'ShowProgress', 'on', ...
    'SetupFcn', @() sldemo_parsim_paramsweep_suspn_raccel_setup(mdl));
[14-Aug-2017 18:48:02] Checking for availability of parallel pool...
Starting parallel pool (parpool) using the 'local' profile ...
connected to 12 workers.
[14-Aug-2017 18:49:01] Loading Simulink on parallel workers...
Analyzing and transferring files to the workers ...done.
[14-Aug-2017 18:49:26] Loading model on parallel workers...
[14-Aug-2017 18:49:29] Configuring simulation cache folder on parallel workers...
[14-Aug-2017 18:49:36] Running SetupFcn on parallel workers...
[14-Aug-2017 18:50:05] Running simulations...
[14-Aug-2017 18:50:11] Completed 1 of 10 simulation runs
[14-Aug-2017 18:50:11] Completed 2 of 10 simulation runs
[14-Aug-2017 18:50:11] Completed 3 of 10 simulation runs
[14-Aug-2017 18:50:11] Completed 4 of 10 simulation runs
[14-Aug-2017 18:50:11] Completed 5 of 10 simulation runs
[14-Aug-2017 18:50:11] Completed 6 of 10 simulation runs
[14-Aug-2017 18:50:11] Completed 7 of 10 simulation runs
[14-Aug-2017 18:50:11] Completed 8 of 10 simulation runs
[14-Aug-2017 18:50:11] Completed 9 of 10 simulation runs
[14-Aug-2017 18:50:11] Completed 10 of 10 simulation runs

Each SimulationOutput object contains the logged signal along with the SimulationMetadata. When running multiple simulations using parsim, errors are captured so that subsequent simulations can continue to run. Any errors would show up in the ErrorMessage property of the SimulationOutput object.

Plot Results

Plot the vertical vehicle displacement from the different simulations to see how varying the vehicle mass affected the vehicle dynamics. Use the get method of the SimulationOutput object to obtain the time and signal data contained in each element of simout.

legend_labels = cell(1,numSims);
for i = 1:numSims
        simOut = out(i);
        ts = simOut.logsout.get('vertical_disp').Values;
        ts.plot;
        legend_labels{i} = ['Run ' num2str(i)];
        hold all
end
title('Response of a 3-DoF Suspension Model')
xlabel('Time (s)');
ylabel('Vehicle vertical displacement (m)');
legend(legend_labels,'Location','NorthEastOutside');

Close MATLAB Workers

Last, close the parallel pool and the model if they were not previously opened.

if(~isModelOpen)
    close_system(mdl, 0);
end
delete(gcp('nocreate'));
Parallel pool using the 'local' profile is shutting down.
Was this topic helpful?