batch - Run MATLAB script or function on worker

Syntax

Arguments

j	The batch job object.
'aScript'	The script of MATLAB code to be evaluated by the MATLAB pool job.
myCluster	Cluster object representing cluster compute resources.
fcn	Function handle or string of function name to be evaluated by the MATLAB pool job.
N	The number of output arguments from the evaluated function.
{x1, ..., xn}	Cell array of input arguments to the function.
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 in the cluster defined in the default cluster profile. The function returns j, a handle to the job object that runs the script. The script file aScript.m is added to the AttachedFiles property of the job and 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 added to the AttachedFiles property of the job and copied to the worker.

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(..., 'p1', v1, 'p2', v2, ...) allows additional parameter-value pairs that modify the behavior of the job. These parameters support batch for functions and scripts, unless otherwise indicated. 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. This parameter supports only the running of scripts.

• 'Profile' — A single string that is the name of a cluster profile to use 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 string or cell array of strings that defines paths to be added to the workers' search path before the script or function is executed.

• 'AttachedFiles' — A string or cell array of strings. Each string in the list identifies either a file or a folder, which is transferred to the worker. The script being run is always added to the list of files sent to the worker.

• 'CurrentFolder' — A string 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 string for this argument is '.', there is no change in folder before batch execution.

• '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 nonnegative scalar integer that defines the number of workers to make into a MATLAB pool for the job to run on 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. A value of N for the property Matlabpool is effectively the same as adding a call to matlabpool N into the code. Because the MATLAB pool requires N workers in addition to the worker running the batch, there must be at least N+1 workers available on the cluster. (See Run a Batch Parallel Loop.) The default value is 0, which causes the script or function to run on only the single worker without a MATLAB pool.

Tips

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.

Examples

Run a batch script on a worker, without using a MATLAB 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 MATLAB pool job on a remote cluster, using eight workers for the MATLAB 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', 'matlabpool', 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 MATLAB 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', ...
     'matlabpool', 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

See Also

diary | findJob | load | wait

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS