Main Content

Troubleshoot Variables in parfor-Loops

Ensure That parfor-Loop Variables Are Consecutive Increasing Integers

Loop variables in a parfor-loop must be consecutive increasing integers. For this reason, the following examples return errors:

parfor i = 0:0.2:1      % not integers
parfor j = 1:2:11       % not consecutive
parfor k = 12:-1:1      % not increasing
You can fix these errors by converting the loop variables into a valid range. For example, you can fix the noninteger example as follows:
iValues = 0:0.2:1;
parfor idx = 1:numel(iValues)
    i = iValues(idx);
    ...
end

Avoid Overflows in parfor-Loops

If MATLAB® detects that the parfor-loop variable can overflow, it reports an error.

Overflow conditionExampleSolution

The length of the parfor-loop range exceeds the maximum value of the loop variable type.

Here, MATLAB reports an error because length(-128:127)>maxint('int8'):

parfor idx=int8(-128:127)
    idx;
end

Use a larger data type for the parfor-loop variable. If you want to keep the original data type in your calculations, convert the parfor-loop variable inside the parfor loop.

parfor idx=-128:127
    int8(idx);
end

The initial value of the parfor-loop range equals the minimum value of the loop variable type.

Here, MATLAB reports an error because 0=intmin('uint32'):

parfor idx=uint32(0:1)
    idx;
end

  • Use a larger data type with a lower minimum value, as in the previous solution.

  • Increment the range of values. For example:

    parfor idx=uint32(0:1)+1
    idx-1;
end

Solve Variable Classification Issues in parfor-Loops

When MATLAB recognizes a name in a parfor-loop as a variable, the variable is classified in one of several categories, shown in the following table. Make sure that your variables are uniquely classified and meet the category requirements. parfor-loops that violate the requirement return an error.

ClassificationDescription
Loop VariablesLoop indices
Sliced VariablesArrays whose segments are operated on by different iterations of the loop
Broadcast VariablesVariables defined before the loop whose value is required inside the loop, but never assigned inside the loop
Reduction VariablesVariables that accumulates a value across iterations of the loop, regardless of iteration order
Temporary VariablesVariables created inside the loop, and not accessed outside the loop

To find out which variables you have, examine the code fragment. All variable classifications in the table are represented in this code:

Code fragment containing a parfor-loop in which each variable is labelled according to its classification.

If you run into variable classification problems, consider these approaches before you resort to the more difficult method of converting the body of a parfor-loop into a function.

  • If you use a nested for-loop to index into a sliced array, you cannot use that array elsewhere in the parfor-loop. The code on the left does not work because A is sliced and indexed inside the nested for-loop. The code on the right works because v is assigned to A outside the nested loop. You can compute an entire row, and then perform a single assignment into the sliced output.

    InvalidValid
    A = zeros(4, 10);
parfor i = 1:4
    for j = 1:10
        A(i, j) = i + j;
    end
    disp(A(i, 1))
end
    		 
    A = zeros(4, 10);
parfor i = 1:4
    v = zeros(1, 10);
    for j = 1:10
        v(j) = i + j;
    end
    disp(v(1))
    A(i, :) = v;
end

  • The code on the left does not work because the variable x in parfor cannot be classified. This variable cannot be classified because there are multiple assignments to different parts of x. Therefore parfor cannot determine whether there is a dependency between iterations of the loop. The code on the right works because you completely overwrite the value of x. parfor can now determine unambiguously that x is a temporary variable.

    InvalidValid
    parfor idx = 1:10
    x(1) = 7;
    x(2) = 8;
    out(idx) = sum(x);
end
    		 
    parfor idx = 1:10
    x = [7, 8];
    out(idx) = sum(x);
end

  • This example shows how to slice the field of a structured array. See struct for details. The code on the left does not work because the variable a in parfor cannot be classified. This variable cannot be classified because the form of indexing is not valid for a sliced variable. The first level of indexing is not the sliced indexing operation, even though the field x of a appears to be sliced correctly. The code on the right works because you extract the field of the struct into a separate variable tmpx. parfor can now determine correctly that this variable is sliced. In general, you cannot use fields of structs or properties of objects as sliced input or output variables in parfor.

    InvalidValid
    a.x = [];
parfor idx = 1:10
    a.x(idx) = 7;
end
    		 
    tmpx = [];
parfor idx = 1:10
    tmpx(idx) = 7;
end
a.x = tmpx;

Structure Arrays in parfor-Loops

Creating Structures as Temporaries

You cannot create a structure in a parfor-loop using dot notation assignment. In the code on the left, both lines inside the loop generate a classification error. In the code on the right, as a workaround you can use the struct function to create the structure in the loop or in the first field.

InvalidValid
parfor i = 1:4
    temp.myfield1 = rand();
    temp.myfield2 = i;
end
 
parfor i = 1:4
    temp = struct();
    temp.myfield1 = rand();
    temp.myfield2 = i;
end
parfor i = 1:4
    temp = struct('myfield1',rand(),'myfield2',i);
end

Slicing Structure Fields

You cannot use structure fields as sliced input or output arrays in a parfor-loop. In other words, you cannot use the loop variable to index the elements of a structure field. In the code on the left, both lines in the loop generate a classification error because of the indexing. In the code on the right, as a workaround for sliced output, you employ separate sliced arrays in the loop. Then you assign the structure fields after the loop is complete.

InvalidValid
parfor i = 1:4
    outputData.outArray1(i) = 1/i;
    outputData.outArray2(i) = i^2;
end
 
parfor i = 1:4
    outArray1(i) = 1/i;
    outArray2(i) = i^2;
end
outputData = struct('outArray1',outArray1,'outArray2',outArray2);

The workaround for sliced input is to assign the structure field to a separate array before the loop. You can use that new array for the sliced input.

inArray1 = inputData.inArray1;
inArray2 = inputData.inArray2;
parfor i = 1:4
    temp1 = inArray1(i);
    temp2 = inArray2(i);
end

Converting the Body of a parfor-Loop into a Function

If all else fails, you can usually solve variable classification problems in parfor-loops by converting the body of the parfor-loop into a function. In the code on the left, Code Analyzer flags a problem with variable y, but cannot resolve it. In the code on the right, you solve this problem by converting the body of the parfor-loop into a function.

InvalidValid
function parfor_loop_body_bad
    data = rand(5,5);
    means = zeros(1,5);
    parfor i = 1:5
        % Code Analyzer flags problem 
        % with variable y below  
        y.mean = mean(data(:,i));
        means(i) = y.mean;
    end
    disp(means);
end
 
function parfor_loop_body_good
    data = rand(5,5);
    means = zeros(1,5);
    parfor i = 1:5
        % Call a function instead
        means(i) = computeMeans(data(:,i));
    end
    disp(means);
end

% This function now contains the body
% of the parfor-loop
function means = computeMeans(data)
    y.mean = mean(data);
    means = y.mean;
end
Starting parallel pool (parpool) using the 'Processes' profile ... connected to 4 workers.
    0.6786    0.5691    0.6742    0.6462    0.6307

Unambiguous Variable Names

If you use a name that MATLAB cannot unambiguously distinguish as a variable inside a parfor-loop, at parse time MATLAB assumes you are referencing a function. Then at run-time, if the function cannot be found, MATLAB generates an error. See Variable Names. For example, in the following code f(5) could refer either to the fifth element of an array named f, or to a function named f with an argument of 5. If f is not clearly defined as a variable in the code, MATLAB looks for the function f on the path when the code runs.

parfor i = 1:n
    ...
    a = f(5);
    ...
end

Transparent parfor-loops

The body of a parfor-loop must be transparent: all references to variables must be “visible” in the text of the code. For more details about transparency, see Ensure Transparency in parfor-Loops or spmd Statements.

Global and Persistent Variables

The body of a parfor-loop cannot contain global or persistent variable declarations.

Related Topics