Documentation

A sliced variable is one whose value can be broken up into segments, or slices, which are then operated on separately by different workers. Each iteration of the loop works on a different slice of the array. Using sliced variables is important because this type of variable can reduce communication between the client and workers. Only those slices needed by a worker are sent to it, and only when it starts working on a particular range of indices.

In the this example, a slice of A consists of a single element of that array:

Characteristics of a Sliced Variable

A variable in a parfor-loop is sliced if it has all of the following characteristics. A description of each characteristic follows the list:

• Type of First-Level Indexing — The first level of indexing is either parentheses, (), or braces, {}.

• Fixed Index Listing — Within the first-level parenthesis or braces, the list of indices is the same for all occurrences of a given variable.

• Form of Indexing — Within the list of indices for the variable, exactly one index involves the loop variable.

• Shape of Array — The array maintains a constant shape. In assigning to a sliced variable, the right-hand side of the assignment cannot be [] or '', because these operators attempt to delete elements.

Type of First-Level Indexing. For a sliced variable, the first level of indexing is enclosed in either parentheses, (), or braces, {}.

This table lists the forms for the first level of indexing for arrays sliced and not sliced.

After the first level, you can use any type of valid MATLAB^® indexing in the second and further levels.

The variable A shown here on the left is not sliced; that shown on the right is sliced:

A.q{i,12}                         A{i,12}.q

Fixed Index Listing. Within the first-level parentheses or braces of a sliced variable's indexing, the list of indices is the same for all occurrences of a given variable.

The variable A shown here on the left is not sliced because A is indexed by i and i+1 in different places; the code on the right shown on the right slices A:

parfor i = 1:k
   B(:) = h(A(i), A(i+1));
end

parfor i = 1:k
   B(:) = f(A(i));
   C(:) = g(A{i});
end

The example above on the right shows some occurrences of a sliced variable with first-level parenthesis indexing and with first-level brace indexing in the same loop. This is acceptable.

The following example on the left does not slice A because the indexing of A is not the same in all places. The example on the right slices A and B. The indexing of A is not the same as the indexing of B, but all indexing of A is consistent, and all indexing of B is consistent.

parfor i=1:10
  b = A(1,i) + A(2,i)
end

A = [ 1  2  3  4  5  6  7  8  9  10; 
     10 20 30 40 50 60 70 80 90 100];
B = zeros(1,10);
parfor i=1:10
    for n=1:2
       B(i) = B(i)+A(n,i)
    end
end

Form of Indexing. Within the list of indices for a sliced variable, one of these indices is of the form i, i+k, i-k, k+i, or k-i, where i is the loop variable and k is a constant or a simple (nonindexed) broadcast variable; and every other index is a scalar constant, a simple broadcast variable, a nested for-loop index, colon, or end.

With i as the loop variable, the A variables shown here on the left are not sliced; those on the right are sliced:

A(i+f(k),j,:,3) % f(k) invalid for slicing
A(i,20:30,end)  % 20:30 not scalar
A(i,:,s.field1) % s.field1 not simple broadcast var

A(i+k,j,:,3)
A(i,:,end)
A(i,:,k)

When you use other variables along with the loop variable to index an array, you cannot set these variables inside the loop. In effect, such variables are constant over the execution of the entire parfor statement. You cannot combine the loop variable with itself to form an index expression.

Shape of Array. A sliced variable must maintain a constant shape. The variable A shown here on either line is not sliced:

A(i,:) = [];
A(end + 1) = i;

The reason A is not sliced in either case is because changing the shape of a sliced array would violate assumptions governing communication between the client and workers.

Sliced Input and Output Variables

All sliced variables have the characteristics of being input or output. A sliced variable can sometimes have both characteristics. MATLAB transmits sliced input variables from the client to the workers, and sliced output variables from workers back to the client. If a variable is both input and output, it is transmitted in both directions.

In this parfor-loop, r is a sliced input variable and b is a sliced output variable:

a = 0;
z = 0;
r = rand(1,10);
parfor ii = 1:10
   a = ii;
   z = z + ii;
   b(ii) = r(ii);
end

However, if it is clear that in every iteration, every reference to an array element is set before it is used, the variable is not a sliced input variable. In this example, all the elements of A are set, and then only those fixed values are used:

parfor ii = 1:n
   if someCondition
      A(ii) = 32;
   else
      A(ii) = 17;
   end
   loop code that uses A(ii)
end

Even if a sliced variable is not explicitly referenced as an input, implicit usage might make it so. In the following example, not all elements of A are necessarily set inside the parfor-loop, so the original values of the array are received, held, and then returned from the loop, making A both a sliced input and output variable.

A = 1:10;
parfor ii = 1:10
    if rand < 0.5
        A(ii) = 0;
    end
end