Run MATLAB script or function on worker
j = batch('aScript')
j = batch(myCluster,'aScript')
j = batch(fcn,N,{x1, ..., xn})
j = batch(myCluster,fcn,N,{x1,...,xn})
j = batch(...,'p1',v1,'p2',v2,...)
| The batch job object. |
| The script of MATLAB code to be evaluated by the worker. |
| Cluster object representing cluster compute resources. |
| Function handle or function name to be evaluated by the worker. |
| The number of output arguments from the evaluated function. |
| Cell array of input arguments to the function. |
| Object properties or other arguments to control job behavior. |
| Initial values for corresponding object properties or arguments. |
j = batch('aScript') runs the script code
of the file aScript.m on a worker in the cluster
specified by the default cluster profile. (Note: Do not include the .m file
extension with the script name argument.) The function returns j,
a handle to the job object that runs the script. The script file aScript.m is
copied to the worker.
j = batch(myCluster,'aScript') is identical
to batch('aScript') except that the script runs
on a worker according to the cluster identified by the cluster object myCluster.
j = batch(fcn,N,{x1, ..., xn}) runs the
function specified by a function handle or function name, fcn,
on a worker in the cluster identified by the default cluster profile.
The function returns j, a handle to the job object
that runs the function. The function is evaluated with the given arguments, x1,...,xn,
returning N output arguments. The function file
for fcn is copied to the worker. (Do not include
the .m file extension with the function name argument.)
j = batch(myCluster,fcn,N,{x1,...,xn}) is
identical to batch(fcn,N,{x1,...,xn}) except that
the function runs on a worker in the cluster identified by the cluster
object myCluster.
j = batch(...,' allows
additional parameter-value pairs that modify the behavior of the job.
These parameters support batch for functions and scripts, unless otherwise
indicated. The supported parameters are: p1',v1,'p2',v2,...)
'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. This parameter supports only the running
of scripts.
'Profile' — 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.
'AdditionalPaths' — A character
vector or cell array of character vectors that defines paths to be
added to the MATLAB® search path of the workers before the script
or function executes. 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.
'AttachedFiles' — A character
vector or cell array of character vectors. Each character vector in
the list identifies either a file or a folder, which gets transferred
to the worker.
'AutoAddClientPath'— A logical value
(true or false) that controls
whether user-added-entries on the client's path are added to each worker's
path. The default is true.
'AutoAttachFiles' — A logical
value to specify whether code files should be automatically attached
to the job. If true, the batch script or function
is analyzed and the code files that it depends on are automatically
transferred to the worker. The default is true.
'CurrentFolder' — A character
vector indicating in what folder the script executes. There is no
guarantee that this folder exists on the worker. The default value
for this property is the cwd of MATLAB when
the batch command is executed. If the argument
is '.', there is no change in folder before batch
execution.
'CaptureDiary' — A logical
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.
'EnvironmentVariables'— A character vector, or
cell array of character vectors that specifies the names of environment
variables which are 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.
'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 script or function uses this pool for
execution of statements such as parfor and spmd that are inside the
batch code. 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. You do not need
a parallel pool already running to execute batch; and the new pool that
batch creates is not related to a pool you might already have open. (See
Run a Batch Parallel Loop.) The default value is 0, which causes the script or function to run on
only a single worker without a parallel pool.
Run a batch script on a worker, without using a parallel pool:
j = batch('script1');Run a batch script that requires two additional files for execution:
j = batch('myScript','AttachedFiles',{'mscr1.m','mscr2.m'}); wait(j); load(j);
Run a batch pool job on a remote cluster, using eight workers for the parallel pool in addition to the worker running the batch script. Capture the diary, and load the results of the job into the workspace. This job requires a total of nine workers:
j = batch('script1','Pool',8,'CaptureDiary',true); wait(j); % Wait for the job to finish diary(j) % Display the diary load(j) % Load job workspace data into client workspace
Run a batch pool job on a local worker, which employs two other local workers for the pool. Note, this requires a total of three workers in addition to the client, all on the local machine:
j = batch('script1','Profile','local','Pool',2);
Clean up a batch job’s data after you are finished with it:
delete(j)
Run a batch function on a cluster that generates a 10-by-10 random matrix:
c = parcluster();
j = batch(c,@rand,1,{10,10});
wait(j) % Wait for the job to finish
diary(j) % Display the diary
r = fetchOutputs(j); % Get results into a cell array
r{1} % Display result
To see your batch job’s status or to track its progress,
use the Job Monitor, as described in Job Monitor. You can also use the Job Monitor to retrieve
a job object for a batch job that was created in a different session,
or for a batch job that was created without returning a job object
from the batch call.
As a matter of good programming practice, when you no longer need it, you should delete the job created by the batch function so that it does not continue to consume cluster storage resources.