Main Content

batchsim

Offload simulations to run on a compute cluster

collapse all in page

Syntax

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

Description

example

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

collapse all

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

collapse all

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')

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

Name-Value 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.

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.

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

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

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

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

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

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.

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.

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.

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.

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.

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'.

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

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.

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

collapse all

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

Version History

Introduced in R2018b

See Also

Functions

Classes

Topics