Main Content

parfor

Executefor-loop iterations in parallel on workers

collapse all in page

Syntax

parfor loopVar = initVal:endVal; statements; end
parfor (loopVar = initVal:endVal,M); statements; end
parfor (loopVar = initVal:endVal,opts); statements; end
parfor (loopVar = initVal:endVal,cluster); statements; end

Description

example

parforloopVar=initVal:endVal;statements; endexecutesfor-loop iterations in parallel on workers in a parallel pool.

MATLAB®executes the loop body commands instatementsfor values ofloopVarbetweeninitValandendVal.loopVarspecifies a vector of integer values increasing by 1. If you have Parallel Computing Toolbox™, the iterations ofstatementscan execute on a parallel pool of workers on your multi-core computer or cluster. As with afor-loop, you can include a single line or multiple lines instatements.

找出parforcan help increase your throughput, seeDecide When to Use parfor.

parfordiffers from a traditionalfor-loop in the following ways:

example

parfor (loopVar=initVal:endVal,M);statements; endusesMto specify the maximum number of workers from the parallel pool to use in evaluatingstatementsin the loop body.Mmust be a nonnegative integer.

By default, MATLAB uses the available workers in your parallel pool. You can change the number of workers on theHometab in theEnvironmentsection, by selectingParallel>Parallel Preferences. You can override the default number of workers in a parallel pool by usingparpool. When no workers are available in the pool orMis zero, MATLAB still executes the loop body in a nondeterministic order, but not in parallel. Use this syntax to switch between parallel and serial execution when testing your code.

With this syntax, to execute the iterations in parallel, you must have a parallel pool of workers. By default, if you executeparfor, you automatically create a parallel pool of workers on the cluster defined by your default cluster profile. The default cluster islocal. You can change your cluster inParallel Preferences. For more details, seeSpecify Your Parallel Preferences.

parfor (loopVar=initVal:endVal,opts);statements; endusesoptsto specify the resources to use in evaluatingstatementsin the loop body. Create a set ofparforoptions using theparforOptionsfunction. With this approach, you can runparforon a cluster without first creating a parallel pool and control howparforpartitions the iterations into subranges for the workers.

example

parfor (loopVar=initVal:endVal,cluster);statements; endexecutesstatementson workers inclusterwithout creating a parallel pool. This is equivalent to executingparfor (loopVar = initVal:endVal,parforOptions(cluster)); statements; end.

Examples

collapse all

Create aparfor-loop for a computationally intensive task and measure the resulting speedup.

In the MATLAB Editor, enter the followingfor-loop. To measure the time elapsed, addticandtoc.

tic n = 200; A = 500; a = zeros(1,n);fori = 1:n a(i) = max(abs(eig(rand(A))));endtoc

Run the script, and note the elapsed time.

Elapsed time is 31.935373 seconds.

In the script, replace thefor-loop with aparfor-loop.

tic n = 200; A = 500; a = zeros(1,n);parfori = 1:n a(i) = max(abs(eig(rand(A))));endtoc

Run the new script, and run it again. The first run is slower than the second run, because the parallel pool has to be started, and you have to make the code available to the workers. Note the elapsed time for the second run.

By default, MATLAB automatically opens a parallel pool of workers on your local machine.

Elapsed time is 10.760068 seconds.

Observe that you speed up your calculation by converting thefor-loop into aparfor-loop on four workers. You might reduce the elapsed time further by increasing the number of workers in your parallel pool. For more information, seeConvert for-Loops Into parfor-LoopsandScale Up parfor-Loops to Cluster and Cloud.

You can specify the maximum number of workersMfor aparfor-loop. SetM = 0to run the body of the loop in the desktop MATLAB, without using workers, even if a pool is open. WhenM = 0, MATLAB still executes the loop body in a nondeterministic order, but not in parallel, so that you can check whether yourparfor-loops are independent and suitable to run on workers. This is the simplest way to allow you to debug the contents of aparfor-loop. You cannot set breakpoints directly in the body of theparfor-loop, but you can set breakpoints in functions called from the body of theparfor-loop.

SpecifyM = 0to run the body of aparfor循环在桌面MATLABif a pool is open.

M = 0;% M specifies maximum number of workersy = ones(1,100);parfor(i = 1:100,M) y(i) = i;end

To control the number of workers in your parallel pool, seeSpecify Your Parallel Preferencesandparpool.

To measure how much data is transferred to and from the workers in your current parallel pool, addticBytes(gcp)andtocBytes(gcp)before and after theparfor-loop. Usegcpas an argument to get the current parallel pool.

Delete your current parallel pool if you still have one.

delete(gcp('nocreate'))
tic ticBytes(gcp); n = 200; A = 500; a = zeros(1,n);parfori = 1:n a(i) = max(abs(eig(rand(A))));endtocBytes(gcp) toc

Run the new script, and run it again. The first run is slower than the second run, because the parallel pool has to be started, and you have to make the code available to the workers.

By default, MATLAB automatically opens a parallel pool of workers on your local machine.

Starting parallel pool (parpool) using the 'local' profile ... connected to 4 workers. ... BytesSentToWorkers BytesReceivedFromWorkers __________________ ________________________ 1 15340 7024 2 13328 5712 3 13328 5704 4 13328 5728 Total 55324 24168

You can use theticBytesandtocBytesresults to examine the amount of data transferred to and from the workers in a parallel pool. In this example, the data transfer is small. For more information aboutparfor-loops, seeDecide When to Use parforandConvert for-Loops Into parfor-Loops.

Open Live Script

Create a cluster object using theparclusterfunction, and create a set ofparforoptions with it. By default,parcluster使用默认集群配置文件。检查你的default profile on the MATLABHometab, inParallel>Select a Default Cluster.

cluster = parcluster;

To runparforcomputations directly in the cluster, pass the cluster object as the second input argument toparfor.

When you use this approach,parforcan 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. If you want to control other options, including partitioning of iterations, useparforOptions.

values = [3 3 3 7 3 3 3];parfor(i=1:numel(values),cluster) 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.

Input Arguments

collapse all

Loop index variable with initial valueinitValand final valueendVal. The variable can be any numeric type and the value must be an integer.

Make sure that yourparfor-loop variables are consecutive increasing integers. For more help, seeTroubleshoot Variables in parfor-Loops.

The range of theparfor-loop variable must not exceed the supported range. For more help, seeAvoid Overflows in parfor-Loops.

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

Initial value loop index variable,loopVar. The variable can be any numeric type and the value must be an integer. WithendVal, specifies theparforrange vector, which must be of the formM:N.

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

Final value loop index variable,loopVar. The variable can be any numeric type and the value must be an integer. WithinitVal, specifies theparforrange vector, which must be of the formM:N.

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

Loop body, specified as text. The series of MATLAB commands to execute in theparfor-loop.

You might need to modify your code to useparfor-loops. For more help, seeConvert for-Loops Into parfor-Loops

Do not nestparfor-loops, seeNested parfor and for-Loops and Other parfor Requirements.

Maximum number of workers running in parallel, specified as a nonnegative integer. If you specify an upper limit, MATLAB uses no more than this number, even if additional workers are available. If you request more workers than the number of available workers, then MATLAB uses the maximum number of workers available at the time of the call. If the loop iterations are fewer than the number of workers, some workers perform no work.

Ifparforcannot run on multiple workers (for example, if only one core is available orMis 0), MATLAB executes the loop in a serial manner. In this case, MATLAB still executes the loop body in a nondeterministic order. Use this syntax to switch between parallel and serial when testing your code.

parforoptions, specified as aClusterOptionsobject. Use theparforOptionsfunction to create a set ofparforoptions.

Example:opts = parforOptions(parcluster);

Cluster, specified as aparallel.Clusterobject, on whichparforruns. To create a cluster object, use theparclusterfunction.

Example:cluster = parcluster('local')

Data Types:parallel.Cluster

Tips

  • Use aparfor-loop when:

    • You have many loop iterations of a simple calculation.parfordivides the loop iterations into groups so that each thread can execute one group of iterations.

    • You have some loop iterations that take a long time to execute.

  • Do not use aparfor-loop when an iteration in your loop depends on the results of other iterations.

    Reductions are one exception to this rule. Areductionvariable accumulates a value that depends on all the iterations together, but is independent of the iteration order. For more information, seeReduction Variables.

  • When you useparfor, you have to wait for the loop to complete to obtain your results. Your client MATLAB is blocked and you cannot break out of the loop early. If you want to obtain intermediate results, or break out of afor-loop early, tryparfevalinstead.

  • Unless you specify a cluster object, aparfor-loop runs on the existing parallel pool. If no pool exists,parforstarts a new parallel pool, unless the automatic starting of pools is disabled in your parallel preferences. If there is no parallel pool andparforcannot start one, the loop runs serially in the client session.

  • If theAutoAttachFilesproperty in the cluster profile for the parallel pool is set totrue, MATLAB performs an analysis on aparfor-loop to determine what code files are necessary for its execution, seelistAutoAttachedFiles. Then MATLAB automatically attaches those files to the parallel pool so that the code is available to the workers.

  • You cannot call scripts directly in aparfor-loop. However, you can call functions that call scripts.

  • Do not useclearinside aparforloop because it violates workspace transparency. SeeEnsure Transparency in parfor-Loops or spmd Statements.

  • You can run Simulink®models in parallel with theparsimcommand instead of usingparfor-loops. For more information and examples of using Simulink in parallel, seeRunning Multiple Simulations(Simulink).

Version History

Introduced in R2008a

See Also

|||||||||

Topics