batchsim

Offload simulations to run on a compute cluster

Syntax

simjob = batchsim(in)

simJob = batchsim(myCluster,in)

simJob = batchsim(___,Name=Value)

cloudJob = batchsim(cloudCluster, designStudy)

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 options specified using one or more name-value arguments.

cloudJob = batchsim(cloudCluster, designStudy) runs a batch job on a registered remote cloud computing cluster cloudCluster with parameters specified by the designStudy. Running batchsim on the cloud requires Large-Scale Cloud Simulation for Simulink Support Package (Simulink Compiler)™.

The batchsim function 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 function requires Parallel Computing Toolbox™ and MATLAB Parallel Server™ licenses to run the simulations on compute cluster. The batchsim function runs the simulations in serial if a parallel pool cannot be created. If Parallel Computing Toolbox license is not available, the batchsim function issues an error.

Examples

Run Parallel Simulations with batchsim

This example shows how to run parallel simulations in batch. The batchsim function 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")

Define a set of values for different temperatures. Here, the setPointValues are a standard range of temperatures. The length of the vector helps create an array of Simulink.SimulationInput objects in the following step.

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

Using the setPointValues vector, initialize a vector of Simulink.SimulationInput objects.

in(1:spvLength) = Simulink.SimulationInput('ex_sldemo_househeat');
for k = 1:1:spvLength 
    in(k) = setBlockParameter(in(k),"ex_sldemo_househeat/Set Point",...
        "Value",num2str(setPointValues(k)));
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. For this example, assume that three workers are available to run a batch job for the parallel simulations. The job object contains useful metadata. You can use the job ID to access the job object later from any machine. The NumWorkers indicates how many workers are running the simulations. NumWorkers is always the number of workers specified using the Pool name-value argument and an additional head worker. In this example, Pool is set to 3. You can change the value of Pool based on the availability of the workers.

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 function. The fetchOutputs function retrieves the results from the workers and returns an array of Simulink.SimulationOutput objects.

out = fetchOutputs(simJob)

1x11 Simulink.SimulationOutput array

Input Arguments

in — Inputs and configurations for batch simulations

array of Simulink.SimulationInput objects

Inputs and configurations for batch simulations, specified as an array of Simulink.SimulationInput objects. The SimulationInput object stores initial state, external input, variable, and parameter values to use in each simulation.

myCluster — Cluster in which to run batch simulations

parallel.Cluster object

Cluster in which to run batch simulations, specified as a parallel.Cluster (Parallel Computing Toolbox) object.

cloudCluster — Remote cloud computing cluster name

simulink.cloud.Cluster object

Name of the cluster to run simulations, specified as a simulink.cloud.Cluster object. This requires Large-Scale Cloud Simulation for Simulink™ support package.

designStudy — Inputs and configurations for massive parallel simulations

simulink.multisim.DesignStudy

Inputs and configurations for massive parallel simulations, specified as a simulink.multisim.DesignStudy object.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: Pool=5

AdditionalPaths — Locations to add to MATLAB path on workers

character vector | cell array of character vectors

Locations to add to MATLAB path on workers, specified as a character vector or a cell array of character vectors that define paths to the locations. The batchsim function adds the specified paths to the MATLAB search path on each worker before starting the simulations on the workers. The default search path on the workers might differ from the default search path on the client. The path difference could be the result of different current working directories (pwd), different platforms, or differences in network file system access. The AdditionalPaths argument can assure that workers have access to the necessary files for the simulation, such as code, data, and model files.

AttachedFiles — Files to attach to parallel pool

cell array of character vectors

Files to attach to parallel pool, specified as a cell array of character vectors.

AutoAddClientPath — Option to add custom additions to client path to each worker path

"true" (default) | "false"

Option to add custom additions to client path to each worker path, specified as "true" or "false".

AutoAttachFiles — Option to attach code files to job automatically

"true" (default) | "false"

Option to attach code files to job automatically, specified as "true" or "false".

CaptureDiary — Option to collect diary

"true" (default) | "false"

Option to collect diary, specified as "true" or "false".

CleanupFcn — Function to run once per worker after running simulations

function handle

Function to run once per worker after running simulations, specified as a function handle.

EnvironmentVariables — Environment variables to copy from client to workers

character vector | cell array of character vectors

Environment variables to copy from client to workers, specified as a character vector or a cell array of character vectors. 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 — Option to manage model dependencies

"on" (default) | "off"

Option to manage model dependencies, specified as "on" or "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 — Number of workers in parallel pool in addition to the worker that runs the batch job

integer

Number of workers in parallel pool in addition to the worker that runs the batch job, specified as an integer. The simulations use this pool for execution. Because the pool requires N workers in addition to the worker running the batch, the cluster must have at least N+1 clusters available.

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 to run once per worker before starting simulations

function handle

Function to run once per worker before starting simulations, specified as a function handle.

Note

To avoid a compilation error, either set the LoadExternalInput parameter for the model to "off" or ensure that the specified external input is available when using buildRapidAcceleratorTarget.

ShowProgress — Option to show progress of simulations in diary

"on" | "off"

Option to show progress of simulations in diary, specified as "on" or "off". Set to "on", to copy the progress of the simulations in the MATLAB Command Window to diary of Simulink.Simulation.Job object. The progress is hidden when set to "off".

StopOnError — Option to skip remaining simulations if simulation error occurs

"off" (default) | "on"

Option to skip remaining simulations if simulation error occurs, specified as "off" or "on". Specifying the StopOnError argument as "on" stops the execution of simulations if a simulation error occurs.

TransferBaseWorkspaceVariables — Option to transfer variables to parallel workers

"off" (default) | "on"

Option to transfer variables to parallel workers, specified as "off" or "on". When TransferBaseWorkspaceVariables is set to "on", variables used in the model and defined in the base workspace are transferred to the parallel workers.

UseFastRestart — Option to use fast restart in simulations

"off" (default) | "on"

Option to use fast restart in simulations, specified as "off" or "on". When UseFastRestart is set to "on", simulations run on the workers using fast restart.

Output Arguments

simjob — Batch job metadata and access to simulation outputs

Simulink.Simulation.Job object

Batch job metadata and access to simulation outputs, returned as a Simulink.Simulation.Job object. The properties of the Simulink.Simulation.Job object provide metadata for the batch job, including information about the batch job configuration and progress. Check the batch job status using the State property.

To access the outputs of the batch simulations, use the fetchOutputs function.

Extended Capabilities

Automatic Parallel Support

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

Using the batchsim function 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 Running Multiple Simulations.

Version History

Introduced in R2018b