MATLAB® supports an important exception, called reduction, to the rule that loop
iterations must be independent. A reduction variable accumulates a
value that depends on all the iterations together, but is independent of the iteration
order. MATLAB allows reduction variables in
Reduction variables appear on both sides of an assignment statement, such as any of
the following, where
expr is a MATLAB expression.
|See Associativity in Reduction Assignments in Requirements for Reduction Assignments|
Each of the allowed statements listed in this table is referred to as a reduction assignment. By definition, a reduction variable can appear only in assignments of this type.
The general form of a reduction assignment is
The following example shows a typical usage of a reduction variable
X = 0; % Do some initialization of X parfor i = 1:n X = X + d(i); end
This loop is equivalent to the following, where you calculate each
d(i) by a different iteration.
X = X + d(1) + ... + d(n)
In a regular
for-loop, the variable
get its value either before entering the loop or from the previous iteration of the
loop. However, this concept does not apply to
parfor-loop, the value of
X is never
transmitted from client to workers or from worker to worker. Rather, additions of
d(i) are done in each worker, with
over the subset of
1:n being performed on that worker. The results
are then transmitted back to the client, which adds the partial sums of the workers into
X. Thus, workers do some of the additions, and the client does
parfor code does not adhere to the guidelines and
restrictions labeled as Required, you get an error.
MATLAB catches some of these errors at the time it reads the code, and others
when it executes the code. These errors are labeled as Required (static) or Required
(dynamic) respectively. Guidelines that do not cause errors are
labeled as Recommended. You can use MATLAB Code Analyzer to help
parfor-loops comply with the
The following requirements further define the reduction assignments associated with a given variable.
|Required (static): For any reduction variable, the same reduction function or operation must be used in all reduction assignments for that variable.|
parfor-loop on the left is not valid because the
reduction assignment uses
+ in one instance, and
[,] in another. The
parfor-loop on the
right is valid.
parfor i = 1:n if testLevel(k) A = A + i; else A = [A, 4+i]; end % loop body continued end
parfor i = 1:n if testLevel(k) A = A + i; else A = A + i + 5*k; end % loop body continued end
|Required (static): If the
reduction assignment uses |
parfor-loop on the left is not valid because the order of
items in the concatenation is not consistent throughout the loop. The
parfor-loop on the right is valid.
parfor i = 1:n if testLevel(k) A = [A, 4+i]; else A = [r(i), A]; end % loop body continued end
parfor i = 1:n if testLevel(k) A = [A, 4+i]; else A = [A, r(i)]; end % loop body continued end
|Required (static): You cannot index or subscript a reduction variable.|
The code on the left is not valid because it tries to index
and so MATLAB cannot classify it as a reduction variable. To fix it, the code on the
right uses a non-indexed variable.
a.x = 0 parfor i = 1:10 a.x = a.x + 1; end
tmpx = 0 parfor i = 1:10 tmpx = tmpx + 1; end a.x = tmpx;
Reduction Assignments. In addition to the specific forms of reduction assignment listed in the table in Reduction Variables, the only other (and more general) form of a reduction assignment is
f is a variable, then for all practical purposes its value
at run time is a function handle. However, as long as the right side can be
evaluated, the resulting value is stored in
parfor-loop on the left does not execute correctly
because the statement
f = @times causes
be classified as a temporary variable. Therefore
f is cleared at
the beginning of each iteration. The
parfor-loop on the right
is correct, because it does not assign
f inside the loop.
f = @(x,k)x * k; parfor i = 1:n a = f(a,i); % loop body continued f = @times; % Affects f end
f = @(x,k)x * k; parfor i = 1:n a = f(a,i); % loop body continued end
|| are not
listed in the table in Reduction Variables. Except for
||, all the matrix
operations of MATLAB have a corresponding function
f, such that
u op v is equivalent to
||, such a function cannot
be written because
or might not evaluate
v before calling
|| are excluded from the table of allowed reduction
assignments for a
Every reduction assignment has an associated function
f that ensure deterministic behavior of a parfor
statement are discussed in the following sections.
Associativity in Reduction Assignments. The following practice is recommended for the function
f, as used in the definition of a reduction variable.
However, this rule does not generate an error if not adhered to. Therefore, it is up
to you to ensure that your code meets this recommendation.
|Recommended: To get
deterministic behavior of |
To be associative, the function
f must satisfy the following
f(a,f(b,c)) = f(f(a,b),c)
The classification rules for variables, including reduction variables, are purely
syntactic. They cannot determine whether the
f you have supplied
is truly associative or not. Associativity is assumed, but if you violate this rule,
each execution of the loop might result in different answers.
The addition of mathematical real numbers is associative. However, the
addition of floating-point numbers is only approximately associative. Different
executions of this
parfor statement might produce values of
X with different round-off errors. You cannot avoid this
cost of parallelism.
For example, the statement on the left yields 1, while the statement on the right
returns 1 +
(1 + eps/2) + eps/2 1 + (eps/2 + eps/2)
Except for the minus operator (
-), all special cases listed in
the table in Reduction Variables have a corresponding
(approximately) associative function. MATLAB calculates the assignment
X = X - expr by using
X = X + (-expr). (So, technically, the function for
calculating this reduction assignment is
minus.) However, the assignment
X = expr -
X cannot be written using an associative function, which explains its
exclusion from the table.
f(a,b) = f(b,a)
Noncommutative functions include
* (because matrix
multiplication is not commutative for matrices in which both dimensions have size
greater than one),
Noncommutativity is the reason that consistency in the order of arguments to these
functions is required. As a practical matter, a more efficient algorithm is possible
when a function is commutative as well as associative, and
is optimized to exploit commutativity.
|Recommended: Except in the cases
Violating the restriction on commutativity in a function used for reduction could result in unexpected behavior, even if it does not generate an error.
f is a known noncommutative built-in function, it is
assumed to be commutative. There is currently no way to specify a user-defined,
noncommutative function in
|Recommended: An overload of
|Recommended: An overload of
Similarly, because of the special treatment of
X = X - expr,
the following is recommended.
|Recommended: An overload of the
minus operator (|
Suppose that each iteration of a loop performs some calculation, and you are interested in finding which iteration of a loop produces the maximum value. This reduction exercise makes an accumulation across multiple iterations of a loop. Your reduction function must compare iteration results, until the maximum value can be determined after all iterations are compared.
First consider the reduction function itself. To compare one iteration result against another, the function requires as input the current result and the known maximum from other iterations so far. Each of the two inputs is a vector containing iteration results and iteration number.
function mc = comparemax(A, B) % Custom reduction function for 2-element vector input if A(1) >= B(1) % Compare the two input data values mc = A; % Return the vector with the larger result else mc = B; end end
Inside the loop, each iteration calls the reduction function
comparemax), passing in a pair of two-element
The accumulated maximum and its iteration index, which is the reduction
The iteration value and index
If the data value of the current iteration is greater than the maximum in
cummmax, the function returns a vector of the new value and
its iteration number. Otherwise, the function returns the existing maximum and its
Each iteration calls the reduction function
compare its own data
[dat i] to data already accumulated in
cummax. Try the following code for this loop.
% First element of cummax is maximum data value % Second element of cummax is where (iteration) maximum occurs cummax = [0 0]; % Initialize reduction variable parfor ii = 1:100 dat = rand(); % Simulate some actual computation cummax = comparemax(cummax, [dat ii]); end disp(cummax);
MATLAB classifies assignments of the form
X = expr op X or
X = X op expr as reduction statements when they are
equivalent to the parenthesized assignments
X = (expr) op X or
X = X op (expr) respectively.
X is a
op is a reduction operator, and
is an expression with one or more binary reduction operators. Consequently, due to
the MATLAB operator precedence rules, MATLAB might not classify some assignments of the form
X = expr op1
X op2 expr2 ..., that chain operators, as reduction statements in
In this example, MATLAB classifies
X as a reduction variable because the
assignment is equivalent to
X = X + (1 * 2).
X = 0; parfor i=1:10 X = X + 1 * 2; end
In this example, MATLAB classifies
X as a temporary variable because the
assignment, equivalent to
X = (X * 1) + 2, is not of the form
X = (expr) op X or
X = X op
X = 0; parfor i=1:10 X = X * 1 + 2; end
As a best practice, use parentheses to explicitly specify operator precedence for chained reduction assignments.