parfor

R2026b

Parallel for-loop

Syntax

parfor loopVar = initVal:endVal; statements; end

parfor loopVar = initVal:step:endVal; statements;end

parfor(loopVar = initVal:endVal); statements; end

parfor(loopVar = initVal:step:endVal); statements; end

parfor(___,M); statements; end

Description

parfor loopVar = initVal:endVal; statements; end increments the loop variable, loopVar, from initVal to endVal by 1, and executes MATLAB^® statements for each value. The initVal:endVal range must evaluate to a vector of increasing integer values or be empty.

The loop runs in parallel when you have Parallel Computing Toolbox™ or when you create a MEX function or standalone code with MATLAB Coder™. Unlike a traditional for-loop, iterations are not executed in a guaranteed order. You cannot call scripts directly in a parfor-loop. However, you can call functions that call scripts.

parfor loopVar = initVal:step:endVal; statements;end increments loopVar by the value of step on each iteration, or decrements loopVar when the value of step is negative. step must be 1 or -1. Use this syntax to run parfor-loops with a descending loop index variable.

If you use this syntax, loop iterations must be consecutive integer values.

Before R2026a: step must be 1 and loop iterations must be consecutive, increasing integer values.

parfor(loopVar = initVal:endVal); statements; end and parfor(loopVar = initVal:step:endVal); statements; end also execute statements in a loop. Use parenthesis around the loop expression to allow for additional options.

parfor(___,M); statements; end uses M to specify the maximum number of workers or threads to use in evaluating statements in the loop body. M must be a nonnegative integer.

Examples

Calculate Eigenvalues Using Three Workers

Perform three large eigenvalue computations using three workers or cores with Parallel Computing Toolbox:

parpool(3)
parfor ii = 1:3 
    c(:,ii) = eig(rand(1000)); 
end

Run parfor-Loop with Descending Range

Since R2026a

Use a parfor-loop with a descending range to evaluate a mathematical expression on the workers.

Specify an initial value of 12, step size of -1, and an end value of 1. The parfor-loop iterates from 12 down to 1.

parfor k = 12:-1:1
    out(k) = (5.*(k+8))./2;
end

Input Arguments

loopVar — Loop index

integer

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

Make sure that your parfor-loop variables are consecutive integers. For more details, see Troubleshoot Variables in parfor-Loops (Parallel Computing Toolbox).

Before R2026a: Loop iterations must be consecutive, increasing integer values.

The range of the parfor-loop variable must not exceed the supported range. For more help, see Avoid Overflows in parfor-Loops (Parallel Computing Toolbox).

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

initVal — Initial value of loop index

integer

Initial value loop index variable, loopVar. The variable can be any numeric type and the value must be an integer. With endVal, specifies the parfor range vector, when in the form M:N.

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

endVal — Final value of loop index

integer

Final value loop index variable, loopVar. The variable can be any numeric type and the value must be an integer. With initVal, specifies the parfor range vector, when in the form M:N.

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

step — Step size of loop index

1 | -1

Step size of loop index, loopVar. The variable can be any numeric type and must be an integer of value 1 or -1 to ensure the loop iterations are consecutive integer values.

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

statements — Loop body

text

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

You might need to modify your code to use parfor-loops. For more help, see Convert for-Loops into parfor-Loops (Parallel Computing Toolbox).

Do not nest parfor-loops, see Nested parfor and for-Loops and Other parfor Requirements (Parallel Computing Toolbox).

M — Maximum number of workers running in parallel

number of workers in the parallel pool (default) | nonnegative integer

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.

If parfor cannot run on multiple workers (for example, if only one core is available or M is 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.

Tips

• If you have Parallel Computing Toolbox, see parfor (Parallel Computing Toolbox) and parpool (Parallel Computing Toolbox) for additional information.

• If you have MATLAB Coder, see parfor (MATLAB Coder) for additional information.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Treated as a for-loop in a MATLAB Function block or when used with fiaccel.

• See parfor (MATLAB Coder) in MATLAB Coder.

• See Generate Code with Parallel for-Loops (MATLAB Coder).

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same usage notes and limitations apply to GPU code generation.

Automatic Parallel Support

Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

If you have Parallel Computing Toolbox installed, then when you use parfor, MATLAB automatically opens a parallel pool of workers on your local machine. MATLAB runs the loop across the available workers. Control parallel behavior with the parallel settings, including scaling up to a cluster.

For details, see Parallel for-Loops (parfor) (Parallel Computing Toolbox).

Version History

Introduced in R2008a

R2026a: Use consecutive decreasing integers as loop variables

Starting in R2026a, you can now use consecutive decreasing integers as loop index variables in a parfor-loop. Loop index variables that are consecutive decreasing integers allow you to simplify code where reverse iteration is needed. MATLAB continues to execute parfor-loop iterations in a nondeterministic order.

For example, use a parfor-loop to square a number for values of n between 10 and 1. The parfor-loop index variable range n has a range step value of -1.

parfor n = 10:-1:1
  out(n) = n^2;
end