batchsim - Offload simulations to run on a compute cluster - MATLAB (original) (raw)

Offload simulations to run on a compute cluster

Syntax

Description

[simjob](#mw%5Fce1cc08f-42c1-42e6-9fe0-0ae326c71c1a) = batchsim([in](#mw%5F7aa2a121-a82a-4618-85b1-2cd4469bc02e)) runs a batch job on a single worker to simulate a model using the inputs specified in theSimulationInput object, in.

`simJob` = batchsim([myCluster](#mw%5F424e2279-a1ff-4333-8796-d133192e9f14),[in](#mw%5F7aa2a121-a82a-4618-85b1-2cd4469bc02e)) runs a batch job on the cluster identified by the cluster objectmyCluster. 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](#namevaluepairarguments)) 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](#mw%5F5b638eff-a1a2-4ab9-84d6-a60d3a60f02c), [designStudy](#mw%5F913385a9-acf9-4b41-928d-f1c98c92d316)) runs a batch job on a registered remote cloud computing clustercloudCluster with parameters specified by thedesignStudy. Running batchsim on the cloud requiresLarge-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. Thebatchsim 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.

example

Examples

collapse all

This example shows how to run parallel simulations in batch. Thebatchsim 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, thesetPointValues 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 ofSimulink.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 jobID to access the job object later from any machine. TheNumWorkers indicates how many workers are running the simulations.NumWorkers is always the number of workers specified using thePool 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

collapse all

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.

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

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

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

Name-Value Arguments

collapse all

Specify optional pairs of arguments asName1=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

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

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

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

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

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

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

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.

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.

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 workers available.

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.

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

Note

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

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 ofSimulink.Simulation.Job object. The progress is hidden when set to"off".

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

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

A location path for saving simulation outputs (including logging and input metadata) while running parsim thesimulink.multisim.DesignStudy object. TheOutputLocation is specified as one of these:

Output Arguments

collapse all

Batch job metadata and access to simulation outputs, returned as a Simulink.Simulation.Job object. The properties of theSimulink.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

expand all

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

See Also

Functions

Objects

Topics