Parallel Computing Toolbox™

dfeval - Evaluate function using cluster

Syntax

[y1,...,ym] = dfeval(F, x1,...,xn)
y = dfeval( ..., 'P1',V1,'P2',V2,...)
[y1,...,ym] = dfeval(F, x1,...,xn, ... 'configuration', 'ConfigurationName',...)

Arguments

Description

[y1,...,ym] = dfeval(F, x1,...,xn) performs the equivalent of an feval in a cluster of machines using Parallel Computing Toolbox™ software. dfeval evaluates the function F, with arguments provided in the cell arrays x1,...,xn. F can be a function handle, a function name, or a cell array of function handles/function names where the length of the cell array is equal to the number of tasks to be executed. x1,...,xn are the inputs to the function F, specified as cell arrays in which the number of elements in the cell array equals the number of tasks to be executed. The first task evaluates function F using the first element of each cell array as input arguments; the second task uses the second element of each cell array, and so on. The sizes of x1,...,xn must all be the same.

The results are returned to y1,...,ym, which are column-based cell arrays, each of whose elements corresponds to each task that was created. The number of cell arrays (m) is equal to the number of output arguments returned from each task. For example, if the job has 10 tasks that each generate three output arguments, the results of dfeval are three cell arrays of 10 elements each. When evaluation is complete, dfeval destroys the job.

y = dfeval( ..., 'P1',V1,'P2',V2,...) accepts additional arguments for configuring different properties associated with the job. Valid properties and property values are

• Job object property value pairs, specified as name/value pairs or structures. (Properties of other object types, such as scheduler, task, or worker objects are not permitted. Use a configuration to set scheduler and task properties.)

• 'JobManager','JobManagerName'. This specifies the job manager on which to run the job. If you do not use this property to specify a job manager, the default is to run the job on the first job manager returned by findResource.

• 'LookupURL','host:port'. This makes a unicast call to the job manager lookup service at the specified host and port. The job managers available for this job are those accessible from this lookup service. For more detail, see the description of this option on the findResource reference page.

• 'StopOnError',true|{false}. You may also set the value to logical 1 (true) or 0 (false). If true (1), any error that occurs during execution in the cluster will cause the job to stop executing. The default value is 0 (false), which means that any errors that occur will produce a warning but will not stop function execution.

[y1,...,ym] = dfeval(F, x1,...,xn, ... 'configuration', 'ConfigurationName',...) evaluates the function F in a cluster by using all the properties defined in the configuration ConfigurationName. The configuration settings are used to find and initialize a scheduler, create a job, and create tasks. For details about defining and applying configurations, see Programming with User Configurations. Note that configurations enable you to use dfeval with any type of scheduler.

Note that dfeval runs synchronously (sync); that is, it does not return the MATLAB^® prompt until the job is completed. For further discussion of the usage of dfeval, see Evaluating Functions Synchronously.

Examples

Create three tasks that return a 1-by-1, a 2-by-2, and a 3-by-3 random matrix.

y = dfeval(@rand,{1 2 3})
y = 
    [    0.9501]
    [2x2 double]
    [3x3 double]

Create two tasks that return random matrices of size 2-by-3 and 1-by-4.

y = dfeval(@rand,{2 1},{3 4});
y{1}
ans =
    0.8132    0.1389    0.1987
    0.0099    0.2028    0.6038
y{2}
ans =
    0.6154    0.9218    0.1763    0.9355

Create two tasks, where the first task creates a 1-by-2 random array and the second task creates a 3-by-4 array of zeros.

y = dfeval({@rand @zeros},{1 3},{2 4});
y{1}
ans =
    0.0579    0.3529
y{2}
ans =
     0     0     0     0
     0     0     0     0
     0     0     0     0

Create five random 2-by-4 matrices using MyJobManager to execute tasks, where the tasks time out after 10 seconds, and the function will stop if an error occurs while any of the tasks are executing.

y = dfeval(@rand,{2 2 2 2 2},{4 4 4 4 4}, ...
'JobManager','MyJobManager','Timeout',10,'StopOnError',true);

Evaluate the user function myFun using the cluster as defined in the configuration myConfig.

y = dfeval(@myFun, {task1args, task2args, task3args}, ...
    'configuration', 'myConfig', ...
    'FileDependencies', {'myFun.m'});

See Also

dfevalasync, feval, findResource

destroy

dfevalasync