Learn more about Parallel Computing Toolbox

batch - Run MATLAB script as batch job

Syntax

j = batch('aScript') j = batch(..., 'p1', v1, 'p2', v2, ...)

Arguments

`j`	The MATLAB pool job object.
`'aScript'`	The script of M-code to be evaluated by the MATLAB pool job.
`p1`, `p2`	Object properties or other arguments to control job behavior.
`v1`, `v2`	Initial values for corresponding object properties or arguments.

Description

j = batch('aScript') runs the script aScript.m on a worker according to the scheduler defined in the default parallel configuration. The function returns j, a handle to the job object that runs the script. The script file aScript.m is added to the FileDependencies and copied to the worker.

j = batch(..., 'p1', v1, 'p2', v2, ...) allows additional parameter-value pairs that modify the behavior of the job. The accepted parameters are:

'Workspace' — A 1-by-1 struct to define the workspace on the worker just before the script is called. The field names of the struct define the names of the variables, and the field values are assigned to the workspace variables. By default this parameter has a field for every variable in the current workspace where batch is executed.
'Configuration' — A single string that is the name of a parallel configuration to use to find the correct cluster. By default it is the string returned from defaultParallelConfig. If you want the configuration's settings applied to the job properties, you must explicitly specify the configuration, even if using the default. To apply properties from the default parallel configuration, specify it with:
```
batch(...,'Configuration', defaultParallelConfig)
```
'PathDependencies' — A string or cell array of strings that defines paths to be added to the workers' MATLAB path before the script is executed.
'FileDependencies' — A string or cell array of strings. Each string in the list identifies either a file or a directory, which is transferred to the worker.
'CurrentDirectory' — A string to indicate in what directory the script executes. There is no guarantee that this directory exists on the worker. The default value for this property is the cwd of MATLAB when the batch command is executed, unless any FileDependencies are defined.
'CaptureDiary' — A boolean flag to indicate that the toolbox should collect the diary from the function call. See the diary function for information about the collected data. The default is true.
'Matlabpool' — A positive scalar integer that defines the number of labs to make into a MATLAB pool for the job to run on in addition to the worker running the batch script. The script uses the pool for execution of statements such as parfor and spmd. A value of N for the property Matlabpool is effectively the same as adding a call to matlabpool N into the script. Because the MATLAB pool requires N workers in addition to the worker running the batch script, there must be at least N+1 workers available on the cluster. The default value is 0, which causes the script to run on only the single worker without a MATLAB pool.

Remarks

As a matter of good programming practice, when you no longer need it, you should destroy the job created by the batch function so that it does not continue to consume cluster storage resources.

Examples

Run a batch script on a worker without using a MATLAB pool:

 j = batch('script1', 'matlabpool', 0);

Run a batch MATLAB pool job on a remote cluster, using eight workers for the MATLAB pool in addition to the worker running the batch script. This job requires a total of nine workers:

 j = batch('script1', 'matlabpool', 8);

Run a batch MATLAB pool job on a local worker, which employs two other local workers:

 j = batch('script1', 'configuration', 'local', ...
     'matlabpool', 2);

Clean up a batch job's data after you are finished with it:

destroy(j)