parforOptions

Options for parfor, such as partitioning iterations

Description

example

opts = parforOptions(cluster) creates a set of options for parfor that instructs parfor to execute statements on workers in cluster without creating a parallel pool. Instead, parfor submits independent tasks to the cluster to execute the body of the loop. parfor partitions and distributes iterations to workers according to the NumWorkers property, the number of workers available, of cluster.

example

opts = parforOptions(pool) creates a set of options for parfor that instructs parfor to execute statements on workers in the parallel pool pool.

example

opts = parforOptions(___,'RangePartitionMethod',method) uses method to define how to divide parfor-loop iterations into subranges. A subrange is a contiguous block of loop iterations that parfor executes as a group on a worker.

example

opts = parforOptions(___,'RangePartitionMethod','fixed','SubrangeSize',n) divides parfor-loop iterations into subranges of size no larger than n.

example

opts = parforOptions(cluster,___,Name,Value) specifies additional options for use with the cluster object cluster.

Examples

collapse all

Create a cluster object using the parcluster function, and create a set of parfor options with it. By default, parcluster uses your default cluster profile. Check your default profile on the MATLAB® Home tab, in Parallel > Select a Default Cluster.

cluster = parcluster;
opts = parforOptions(cluster);

To run parfor computations directly in the cluster, pass the parfor options as the second input argument to parfor.

When you use this approach, parfor can use all the available workers in the cluster, and workers become available as soon as the loop completes. This approach is also useful if your cluster does not support parallel pools.

values = [3 3 3 7 3 3 3];
parfor (i=1:numel(values),opts)
    out(i) = norm(pinv(rand(values(i)*1e3)));
end

Use this syntax to run parfor on a large cluster without consuming workers for longer than necessary.

You can control how parfor divides iterations into subranges for the workers with parforOptions. Controlling the range partitioning can optimize performance of a parfor-loop. For best performance, try to split into subranges that are:

  • Large enough that the computation time is large compared to the overhead of scheduling the subrange

  • Small enough that there are enough subranges to keep all workers busy

To partition iterations into subranges of fixed size, create a set of parfor options, set 'RangePartitionMethod' to 'fixed', and specify a subrange size with 'SubrangeSize'.

opts = parforOptions(parcluster,'RangePartitionMethod','fixed','SubrangeSize',2);

Pass the parfor options as the second input argument to parfor. In this case, parfor divides iterations into three groups of 2 iterations.

values = [3 3 3 3 3 3];
parfor (i=1:numel(values),opts)
    out(i) = norm(pinv(rand(values(i)*1e3)));
end

To partition iterations into subranges of varying size, pass a function handle to the 'RangePartitionMethod' name-value pair. This function must return a vector of subrange sizes, and their sum must be equal to the number of iterations. For more information on this syntax, see method.

opts = parforOptions(parcluster,'RangePartitionMethod', @(n,nw) [2 1 1 2]);

Pass the parfor options as the second input argument to parfor. In this case, parfor divides iterations into four groups of 2, 1, 1, and 2 iterations.

values = [3 3 7 7 3 3];
parfor (i=1:numel(values),opts)
    out(i) = norm(pinv(rand(values(i)*1e3)));
end

You can use parforOptions to run parfor on the workers of a parallel pool. Use this approach when you want to reserve a fixed number of workers for the parfor-loop. You can also have finer control on how parfor divides iterations for workers.

Create a parallel pool using the parpool function. By default, parpool uses your default cluster profile. Check your default profile on the MATLAB Home tab, in Parallel > Select a Default Cluster. Create a set of parfor options with the parallel pool object, and specify options. For example, specify subranges of fixed size 2 as the partitioning method.

p = parpool;
Starting parallel pool (parpool) using the 'local' profile ...
Connected to the parallel pool (number of workers: 6).
opts = parforOptions(p,'RangePartitionMethod','fixed','SubrangeSize',2);

Pass the parfor options as the second input argument to the parfor function. parfor runs the loop body on the parallel pool and divides iterations according to opts.

values = [3 3 3 3 3 3];
parfor (i=1:numel(values),opts)
    out(i) = norm(pinv(rand(values(i)*1e3)));
end

When you run parfor with or without a parallel pool, by default, MATLAB performs an automatic dependency analysis on the loop body. MATLAB transfers required files to the workers before running the statements. In some cases, you must explicitly transfer those files to the workers. For more information, see Identify Program Dependencies.

If you are using parfor without a parallel pool, use parforOptions to transfer files. Create a cluster object using the parcluster option. Create a set of parfor options with the cluster object using the parforOptions function. To transfer files to the workers, use the 'AttachedFiles' name-value pair.

cluster = parcluster;
opts = parforOptions(cluster,'AttachedFiles',{'myFile.dat'});

Pass the parfor options as the second input argument to the parfor function. The workers can access the required files in the loop body.

parfor (i=1:2,opts)
    M = csvread('myFile.dat',0,2*(i-1),[0,2*(i-1),1,1+2*(i-1)]);
    out(i) = norm(rand(ceil(norm(M))*1e3));
end

Input Arguments

collapse all

Cluster, specified as a parallel.Cluster object, on which parfor runs. To create a cluster object, use the parcluster function.

Example: opts = parforOptions(parcluster('local'));

Data Types: parallel.Cluster

Subrange size for the fixed partitioning method, specified as a positive integer. You must set the name-value pair 'RangePartitionMethod' to 'fixed'.

Example: opts = parforOptions(cluster,'RangePartitionMethod','fixed','SubrangeSize',5);

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Parallel pool, specified as a parallel.Pool object, on which parfor runs. To create a parallel pool, use the parpool function.

Example: opts = parforOptions(parpool('local'));

Data Types: parallel.Pool

Range partition method, specified as one of the following:

  • 'auto' – This method divides the loop into subranges of varying sizes. It tries to achieve good performance for a variety of parfor-loops.

  • 'fixed' – Partition the parfor-loop into subranges of fixed sizes. You must specify the size of each subrange by setting the 'SubrangeSize' name-value pair.

  • function handle – Use a function handle to divide the loop iterations into subranges. The function must be of the form sizes = customFcn(n,nw), where n is the number of iterations in the parfor-loop, and nw is the number of workers available to execute the loop. When the loop is running on a parallel pool, nw is the number of workers in the parallel pool. When the loop is running using a cluster, nw is the NumWorkers property of the cluster. customFcn returns a vector sizes of subrange sizes. This vector must satisfy sum(sizes) == n. For more information on function handles, see Create Function Handle.

Example: opts = parforOptions(cluster,'RangePartitionMethod','fixed','SubrangeSize',10);

Example: opts = parforOptions(cluster,'RangePartitionMethod',@(n,nw) [2,4,4,n-10]);

Data Types: char | function_handle

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: opts = parforOptions(cluster,'AttachedFiles',{'myFile.dat'});

Flag to specify if client path is added to worker path, specified as the comma-separated pair consisting of AutoAddClientPath and true or false.

Data Types: logical

Flag to enable dependency analysis on the parfor-loop body and transfer required files to the workers, specified as the comma-separated pair consisting of AutoAttachFiles and true or false.

Data Types: logical

Files to transfer to the workers, specified as the comma-separated pair consisting of AttachedFiles and a character vector, string, string array, or cell array of character vectors.

Example: {'myFun.m','myFun2.m'}

Data Types: char | string | cell

Paths to add to the MATLAB® path of the workers before parfor executes, specified as the comma-separated pair consisting of AdditionalPaths and a character vector, string, string array, or cell array of character vectors.

Example: {'some/path/','another/path'}

Data Types: char | string | cell

Output Arguments

collapse all

parfor options, returned as a parforOptions object. To specify options for a parfor-loop, pass a set of parfor options to the second input argument of parfor.

Example: parfor(i=1:10,parforOptions(parcluster)); out(i)=i; end

Introduced in R2019a