Simulink.Simulation.Job class

Package: Simulink
Superclasses:

Execute batchsim to create a Simulink.Simulation.Job object, simJob

Since R2018b

Description

Execute batchsim command with a parallel pool to create a Simulink.Simulation.Job object. The batchsim command offloads multiple simulations to run in batch using the inputs specified with an array of Simulink.SimulationInput objects. You can use this object to monitor the status of a batch job, fetch outputs of a completed batch job, or cancel one or more jobs.

The batchsim command uses the Parallel Computing Toolbox™ license to run the simulations on compute cluster. If a parallel pool cannot be created batchsim runs the simulations in serial. In the absence of Parallel Computing Toolbox™ license, batchsim errors out.

Construction

simJob = batchsim(in) creates a Simulink.Simulation.Job object, simJob, while running multiple simulations in batches on a compute cluster using the inputs specified in the Simulink.SimulationInput object, in.

createSimulationJob(batchJob) creates a Simulink.Simulation.Job object from a parallel.job object, batchJob. Use the createSimulationJob command to retrieve the job object returned by the batchsim command.

Input Arguments

in — Simulink.SimulationInput object array

object (default) | array

A Simulink.SimulationInput object or an array of Simulink.SimulationInput objects used to run multiple simulations. Specify parameters and values of a model to run multiple simulations without making it dirty.

Example: in = Simulink.SimulationInput('vdp'), in(1:10) = Simulink.SimulationInput('vdp')

Properties

AdditionalPaths — Folders to add to MATLAB search path of workers

character vector | string | string array | array of character vectors

Specified folders to add to MATLAB search path of parallel workers.

This property is read-only.

AttachedFiles — Files and folders sent to the workers

character vector | string | string array | array of character vectors

Files and folders to send to the parallel workers.

This property is read-only.

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

true (default) | false

Whether user-added entries on the client path are added to each parallel worker path at the start of the batch job, specified as true or false.

CreateDateTime — Date and time of simJob creation

datetime object

Date and time at which the batch job was created, specified as a datetime object.

This property is read-only.

EnvironmentVariables — Environment variables sent to the workers

character vector | string | string array | array of character vectors

Defines the names of environment variables that are copied from a client session to the parallel workers.

This property is read-only after job submission.

FinishDateTime — Date and time of simJob completion

datetime object

Date and time at when the batch job completes execution, specified as a datetime object.

This property is read-only.

ID — Numeric identifier of the simJob object

scalar integer

ID of the future object, specified as a scalar integer.

This property is read-only.

Name — simJob name

string | character vector

Name of the job object, specified as a string.

Parent — Cluster object containing simJob

parallel.cluster object

Cluster object that contains the Simulink.Simulation.Job object, simJob.

SimulationInputs — Array of Simulink.Simulation.Input objects

Simulink.Simulation.Input object | Array

Array of Simulink.Simulation.Input objects used for simulations for simJob.

StartDateTime — Date and time when simJob starts running

datetime object

Date and time when the Simulink.Simulation.Job starts running, specified as a datetime object.

This property is read-only.

State — Current state of future object array

'pending' | 'queued' | 'running' | 'finished' | 'failed'

Current state of future object array, specified as 'pending', 'queued', 'running', 'finished', or 'failed'.

This property is read-only.

SubmitDateTime — Date and time of simJob submission

datetime object

Date and time when the Simulink.Simulation.Job is submitted, specified as a datetime object.

This property is read-only.

Tag — Label associated with simJob

string

Label associated with Simulink.Simulation.Job object.

Type — Job Type

independent | pool

Type of the Simulink.Simulation.Job object, specified as independent or pool.

UserData — Data associated with simJob

string

Stores any data associated with a job object. The data is stored in a client MATLAB session, and is not available on the workers.

UserName — Name of the user who creates the simJob object

string | character vector

Name of the user who creates the Simulink.Simulation.Job object.

Methods

Method	Purpose
cancel	Cancel a pending, queued, or running Simulink.Simulation.Job object
diary	Display or save Command Window text of batch job
fetchOutputs	Retrieve an array of Simulink.SimulationOutput objects from all simulations in Simulink.Simulation.Job
listAutoAttachedFiles	List of files automatically attached to job, task, or parallel pool
wait	Wait for Simulink.Simulation.Job object to change state

Examples

Run Parallel Simulations With batchsim to Create Simulink.Simulation.Job

This example shows how to run parallel simulations in batch using the sldemo_househeat model. batchsim offloads simulations to the 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.

Observe the model behavior for different temperature set points.

1. Open the model.

open_system('sldemo_househeat');

2. Define a set of values for different temperatures.

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

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

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

4. 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, 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 displays how many workers are running the simulations – the number of workers specified in the 'Pool' argument plus 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

Version History

Introduced in R2018b