batchsim

Offload simulations to run on a compute cluster

Syntax

simJob = batchsim(in)

simJob = batchsim(myCluster,in)

simJob = batchsim(...,Name,Value)

Description

simJob = batchsim(in) runs a batch job on a single worker to simulate a model using the inputs specified in the SimulationInput object, in.

simJob = batchsim(myCluster,in) runs a batch job on the cluster identified by the cluster object myCluster. If a cluster profile is not specified, batchsim uses a default cluster profile as set up in the parallel preferences. For more information, see Discover Clusters and Use Cluster Profiles (Parallel Computing Toolbox).

simJob = batchsim(...,Name,Value) runs a batch job that simulates a model using the inputs specified in the SimulationInput object and the options specified as Name,Value pair.

batchsim offloads simulations to a compute cluster, enabling you to carry out other tasks while the batch job is processing, or close the client MATLAB^® and access the batch job later. Use the 'Pool' argument to run simulations in parallel.

The batchsim command uses the Parallel Computing Toolbox™ and MATLAB Parallel Server™ licenses to run the simulations on compute cluster. batchsim runs the simulations in serial if a parallel pool cannot be created. If Parallel Computing Toolbox license is not available, batchsim errors out.

Examples

Run Parallel Simulations with batchsim

This example shows how to run parallel simulations in batch. batchsim offloads simulations to a compute cluster, enabling you to carry out other tasks while the batch job is processing, or close the client MATLAB and access the batch job later.

This example uses the ex_sldemo_househeat model and runs simulations in batch to observe the model behavior for different temperature set points.

Open the model.

openExample('simulink/OpenTheModelExample');
open_system('ex_sldemo_househeat');
load_system('ex_sldemo_househeat')

Define a set of values for different temperatures.

setPointValues = 65:2:85;
spv_Length = length(setPointValues);

Using the setPointValues, initialize an array of Simulink.SimulationInput objects.

in(1:spv_Length) = Simulink.SimulationInput('ex_sldemo_househeat');
for i = 1:1:spv_Length 
    in(i) = in(i).setBlockParameter('ex_sldemo_househeat/Set Point',...
        'Value',num2str(setPointValues(i)));
end

Specify the pool size of the number of workers to use. In addition to the number of workers used to run simulations in parallel, a head worker is required. In this case, let's assume that three workers are available to run a batch job for the parallel simulations. The job object returns useful metadata as shown. You can use the job ID to access the job object later from any machine. NumWorkers tells you how many workers are running the simulations. NumWorkers is always the number of workers specified in the 'Pool' argument and an additional head worker.

simJob = batchsim(in,'Pool',3)

                  ID: 1
                Type: pool
          NumWorkers: 4
            Username: #####
               State: running
      SubmitDateTime: ##-###-#### ##:##:##
       StartDateTime: 
    Running Duration: 0 days 0h 0m 0s

Access the results of the batch job using the fetchOutputs method. fetchOutputs returns an array of Simulink.SimulationOuput objects.

out = fetchOutputs(simJob)

1x11 Simulink.SimulationOutput array

Input Arguments

in — Simulink.SimulationInput object used to simulate the model

object, array

Specified as a Simulink.SimulationInput object or an array of Simulink.SimulationInput objects that is used to specify changes to the model for simulation.

Example: in = Simulink.SimulationInput('vdp')

myCluster — parallel.Cluster object

object

Cluster object that is used to specify the cluster in which the batch job runs.

Name-Value Pair Arguments

Example: 'Pool', 5

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

'AdditionalPaths' — Files to attach to parallel pool

character vector | cell array

Specified as a character vector, a cell array or an array of character vector to define paths to be added to the MATLAB search path of the workers before the simulations execute. The default search path might not be the same on the workers as it is on the client; the path difference could be the result of different current working folders (pwd), platforms, or network file system access. The 'AdditionalPaths' property can assure that workers are looking in the correct locations for necessary code files, data files, model files, etc.

'AttachedFiles' — Files to attach to parallel pool

cell array

Specified as a cell array of additional files to attach to the parallel pool.

'AutoAddClientPath' — Whether user-added entries on client path are added to each worker path

true (default) | false

Specified as true or false to control whether user-added entries on the client path are added to each worker path.

'AutoAttachedFiles' — Whether code files should be automatically attached to the job

true (default) | false

Specified as true or false to control whether code files are automatically attached to the job.

'CaptureDiary' — Whether diary is collected

true (default) | false

Specified as true or false to indicate collection of the diary.

'CleanupFcn' — Function handle to run once per worker after running simulations

function handle

Specify a function handle to 'CleanupFcn' to run once per worker after the simulations are completed.

'EnvironmentVariables' — Names of environment variables copied from client session to workers

character vector | cell array

Specifies the names of environment variables copied from the client session to the workers. The names specified here are appended to the 'EnvironmentVariables' property specified in the applicable parallel profile to form the complete list of environment variables. Any variables listed which are not set are not copied to the workers. These environment variables will be set on the workers for the duration of the batch job.

'ManageDependencies' — Manage model dependencies

'on' (default) | 'off'

When ManageDependencies is set to 'on', model dependencies are automatically sent to the parallel workers if necessary. If ManageDependencies is set to 'off', explicitly attach model dependencies to the parallel pool.

'Pool' — Size of the number of workers for a parallel pool

integer

An integer specifying the number of workers to make into a parallel pool for the job in addition to the worker running the batch job itself. The simulations use this pool for execution. Because the pool requires N workers in addition to the worker running the batch, there must be at least N+1 workers available on the cluster.

'Profile' — Cluster profile name

profile name

The name of a cluster profile used to identify the cluster. If this option is omitted, the default profile is used to identify the cluster and is applied to the job and task properties.

'SetupFcn' — Function handle to run once per worker

function handle

Specify a function handle to 'SetupFcn' to run once per worker before the start of the simulations.

Note

When buildRapidAcceleratorTarget is used in the SetupFcn and the model has external inputs specified,​ either set 'LoadExternalInput' to 'off' or ensure that the specified external input is available on the workers to prevent compilation error.

'ShowProgress' — Show the progress of the simulations in diary

'on' | 'off'

Set to 'on', to copy the progress of the simulations in the command window to diary of Simulink.Simulation.Job object. The progress is hidden when set to 'off'.

'StopOnError' — Stop simulations on errors

'off' (default) | 'on'

Setting 'StopOnError' to 'on' stops the execution of simulations if an error is encountered.

'TransferBaseWorkspaceVariables' — Transfer variables to the parallel workers

'off' (default) | 'on'

When TransferBaseWorkspaceVariables is set to true, variables used in the model and defined in the base workspace are transferred to the parallel workers.

Note

Use of TransferBaseWorkspaceVariables requires model compilation.

'UseFastRestart' — Use fast restart

'off' (default) | 'on'

When UseFastRestart is set to true, simulations run on the workers using fast restart.

Note

When using batchsim, use the UseFastRestart option and not the FastRestart option. See Get Started with Fast Restart for more information.

Output Arguments

simJob — Simulink.Simulation.Job job object

object

An object containing metadata of submitted batch job. Poll job object using it's ID to check the status of simulations or to access outputs on completion of the job.

Extended Capabilities

Automatic Parallel Support

Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

Using batchsim with Parallel Computing Toolbox installed, MATLAB automatically opens a worker and runs the job in the background on another session on your local machine. Specifying a pool size runs the simulations on the number of workers specified. Control parallel behavior with the parallel preferences, including scaling up to a cluster.

For details, see Run Multiple Simulations.