Evaluate Functions Synchronously

On this page…
Scope of dfeval Arguments of dfeval Example — Use dfeval

Scope of dfeval

When you evaluate a function in a cluster of computers with dfeval, you provide basic required information, such as the function to be evaluated, the number of tasks to divide the job into, and the variable into which the results are returned. Synchronous (sync) evaluation in a cluster means that your MATLAB session is blocked until the evaluation is complete and the results are assigned to the designated variable. So you provide the necessary information, while Parallel Computing Toolbox software handles all the job-related aspects of the function evaluation.

When executing the dfeval function, the toolbox performs all these steps of running a job:

1. Finds a job manager or scheduler

2. Creates a job

3. Creates tasks in that job

4. Submits the job to the queue in the job manager or scheduler

5. Retrieves the results from the job

6. Destroys the job

By allowing the system to perform all the steps for creating and running jobs with a single function call, you do not have access to the full flexibility offered by Parallel Computing Toolbox software. However, this narrow functionality meets the requirements of many straightforward applications. To focus the scope of dfeval, the following limitations apply:

• You can pass property values to the job object; but you cannot set any task-specific properties, including callback functions, unless you use configurations.

• All the tasks in the job must have the same number of input arguments.

• All the tasks in the job must have the same number of output arguments.

• If you are using a third-party scheduler instead of the job manager, you must use configurations in your call to dfeval. See Cluster Profiles, and the reference page for dfeval.

• You do not have direct access to the job manager, job, or task objects, i.e., there are no objects in your MATLAB workspace to manipulate (though you can get them using findResource and the properties of the scheduler object). Note that dfevalasync returns a job object.

• Without access to the objects and their properties, you do not have control over the handling of errors.

Back to Top

Arguments of dfeval

Suppose the function myfun accepts three input arguments, and generates two output arguments. To run a job with four tasks that call myfun, you could type

[X, Y] = dfeval(@myfun, {a1 a2 a3 a4}, {b1 b2 b3 b4}, {c1 c2 c3 c4});

The number of elements of the input argument cell arrays determines the number of tasks in the job. All input cell arrays must have the same number of elements. In this example, there are four tasks.

Because myfun returns two arguments, the results of your job will be assigned to two cell arrays, X and Y. These cell arrays will have four elements each, for the four tasks. The first element of X will have the first output argument from the first task, the first element of Y will have the second argument from the first task, and so on.

The following table shows how the job is divided into tasks and where the results are returned.

Task Function Call	Results
myfun(a1, b1, c1)	X{1}, Y{1}
myfun(a2, b2, c2)	X{2}, Y{2}
myfun(a3, b3, c3)	X{3}, Y{3}
myfun(a4, b4, c4)	X{4}, Y{4}

So using one dfeval line would be equivalent to the following code, except that dfeval can run all the statements simultaneously on separate machines.

[X{1}, Y{1}] = myfun(a1, b1, c1);
[X{2}, Y{2}] = myfun(a2, b2, c2);
[X{3}, Y{3}] = myfun(a3, b3, c3);
[X{4}, Y{4}] = myfun(a4, b4, c4);

For further details and examples of the dfeval function, see the dfeval reference page.

Back to Top

Example — Use dfeval

Suppose you have a function called averages, which returns both the mean and median of three input values. The function might look like this.

function [mean_, median_] = averages (in1, in2, in3)
% AVERAGES Return mean and median of three input values
mean_ = mean([in1, in2, in3]);
median_ = median([in1, in2, in3]);

You can use dfeval to run this function on four sets of data using four tasks in a single job. The input data can be represented by the four vectors,

[1 2 6]
[10 20 60]
[100 200 600]
[1000 2000 6000]

A quick look at the first set of data tells you that its mean is 3, while its median is 2. So,

[x,y] = averages(1,2,6)
x =
     3
y =
     2

When calling dfeval, its input requires that the data be grouped together such that the first input argument to each task function is in the first cell array argument to dfeval, all second input arguments to the task functions are grouped in the next cell array, and so on. Because we want to evaluate four sets of data with four tasks, each of the three cell arrays will have four elements. In this example, the first arguments for the task functions are 1, 10, 100, and 1000. The second inputs to the task functions are 2, 20, 200, and 2000. With the task inputs arranged thus, the call to dfeval looks like this.

[A, B] = dfeval(@averages, {1 10 100 1000}, ...
    {2 20 200 2000}, {6 60 600 6000}, 'jobmanager', ...
    'MyJobManager', 'FileDependencies', {'averages.m'})

A = 
    [   3]
    [  30]
    [ 300]
    [3000]

B = 
    [   2]
    [  20]
    [ 200]
    [2000]

Notice that the first task evaluates the first element of the three cell arrays. The results of the first task are returned as the first elements of each of the two output values. In this case, the first task returns a mean of 3 and median of 2. The second task returns a mean of 30 and median of 20.

If the original function were written to accept one input vector, instead of three input values, it might make the programming of dfeval simpler. For example, suppose your task function were

function [mean_, median_] = avgs (V)
% AVGS Return mean and median of input vector
mean_ = mean(V);
median_ = median(V);

Now the function requires only one argument, so a call to dfeval requires only one cell array. Furthermore, each element of that cell array can be a vector containing all the values required for an individual task. The first vector is sent as a single argument to the first task, the second vector to the second task, and so on.

[A,B] = dfeval(@avgs, {[1 2 6] [10 20 60] ...
    [100 200 600] [1000 2000 6000]}, 'jobmanager', ...
    'MyJobManager', 'FileDependencies', {'avgs.m'})

A = 
    [   3]
    [  30]
    [ 300]
    [3000]

B = 
    [   2]
    [  20]
    [ 200]
    [2000]

If you cannot vectorize your function, you might have to manipulate your data arrangement for using dfeval. Returning to our original data in this example, suppose you want to start with data in three vectors.

v1 = [1 2 6];
v2 = [10 20 60];
v3 = [100 200 600];
v4 = [1000 2000 6000];

First put all your data in a single matrix.

dataset = [v1; v2; v3; v4]
dataset =

       1           2           6
      10          20          60
     100         200         600
    1000        2000        6000

Then make cell arrays containing the elements in each column.

c1 = num2cell(dataset(:,1));
c2 = num2cell(dataset(:,2));
c3 = num2cell(dataset(:,3));

Now you can use these cell arrays as your input arguments for dfeval.

[A, B] = dfeval(@averages, c1, c2, c3, 'jobmanager', ...
    'MyJobManager', 'FileDependencies', {'averages.m'})

A = 
    [   3]
    [  30]
    [ 300]
    [3000]

B = 
    [   2]
    [  20]
    [ 200]
    [2000]

Back to Top

Evaluate Functions in a Cluster

Evaluate Functions Asynchronously

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