J3/13-329
To: J3
From: BSI Fortran Panel
Subject: UK-08 - Generalized reduction intrinsic
Date: 2013 September 30
Requirements and rationale
--------------------------
See N1975.
Specification
--------------
Add an intrinsic function that reduces an array by a user-defined
operation. This should bear the same relationship to CO_REDUCE as
proposed for TS 18508 as SUM does for CO_SUM as proposed for TS 18508.
Similarly to the other reduction intrinsic functions, (a) reduction of a
single dimension shall be provided, and (b) use of a logical mask array
shall be supported. The array to be reduced may be of any intrinsic or
derived type. The result for reduction of a single element shall be that
element. The result for reduction of zero elements shall be specifiable,
and if not specified this result shall be processor dependent.
The user-defined operation shall be mathematically associative but need not
be computationally associative (the proposed CO_REDUCE ought to be the same
as this). When more than two elements are being reduced, the operation may
be applied to elements and intermediate results in any order.
Syntax
------
REDUCE ( ARRAY, OPERATION, DIM [, MASK ] [, IDENTITY]) or
REDUCE ( ARRAY, OPERATION [, MASK ] [, IDENTITY])
The OPERATION function shall be pure, but need not be elemental.
Edits (relative to 10-007r1)
----------------------------
[intro] Add a new extension description
"The new intrinsic function REDUCE performs user-specified array
reductions."
[322] Add at the appropriate place in Table 3.1:
"REDUCE & ( ARRAY, OPERATION, DIM [, MASK ] [, IDENTITY]) or
( ARRAY, OPERATOR [, MASK] [, IDENTITY]) &
T & General reduction of array \\".
{NB: The line breaks here are immaterial, "&" indicates tab to the next
column, "\\" means end of that row.}
[382:2+] Add new subclause following 13.7.138:
"13.7.138a REDUCE ( ARRAY, OPERATION, DIM [, MASK ] [, IDENTITY]) or
REDUCE ( ARRAY, OPERATOR [, MASK] [, IDENTITY])
<> General reduction of array.
<> Transformational function.
<>
ARRAY shall be an array of any type.
OPERATION shall be a pure function with two arguments of the same type
and type parameters as ARRAY. Its result shall have the same
type and type parameters as ARRAY. The arguments and result
shall not be polymorphic. OPERATION shall implement a
mathematically associative operation. When more than two
elements are being reduced, the operation may be applied to
elements and intermediate results in any order. If the
operation is elemental, it may be evaluated in parallel.
DIM shall be an integer scalar with a value in the range
1 <= DIM <= , where is the rank of ARRAY.
MASK (optional) shall be of type logical and shall be conformable
with ARRAY.
IDENTITY (optional} shall be scalar with the same type and type
parameters as ARRAY.
<> The result is of the same type and kind type
parameter as ARRAY. It is scalar if DIM is 1; otherwise, the result has
rank -1 and shape [d_1, d_2, ... , d_DIM-1, d_DIM+1, ... , d_n] where
[d_1, d_2, ... , d_n] is the shape of ARRAY.
<>
Case (i): The result of REDUCE (ARRAY, OPERATION) over the set of
values in ARRAY is the result of an iterative process.
While the set has more than one element, each iteration
involves the execution of r = OPERATION(x,y) for x and y in
the set, the removal of x and y from the set, and the
addition of r to the set. The process continues until the
set has only one element which is the value of the
reduction. If the initial set is empty, the result has the
value IDENTITY if IDENTITY is present, and is processor
dependent otherwise.
Case (ii): The result of REDUCE (ARRAY, OPERATION, MASK = MASK) is as
for Case (i) except that the initial value of the set is
only those elements of ARRAY for which the corresponding
element of MASK is true.
Case (iii): If ARRAY has rank one,
REDUCE (ARRAY, OPERATION, DIM = DIM [, MASK = MASK]) has a
value equal to that of
REDUCE (ARRAY, OPERATION [,MASK = MASK]).
Otherwise, the value of element
(s_1, s_2, ... , s_DIM-1, s_DIM+1, ... , s_n) of
REDUCE (ARRAY, OPERATION, DIM = DIM [ , MASK = MASK])
is equal to
REDUCE (ARRAY (s_1, s_2, ... , s_DIM-1, :, s_DIM+1,
... ,s_n), OPERATION [, MASK=MASK(s_1, s_2, ... , s_DIM-1,
:, s_DIM+1, ... , s_n)]).
<>
The following examples all use the function MY_MULT, which returns the
product of its two integer arguments.
Case (i): The value of REDUCE ([1, 2, 3], MY_MULT) is 6.
Case (ii): REDUCE (C, MY_MULT, MASK= C > 0, IDENTITY=1) forms the
product of the positive elements of C.
Case (iii): If B is the array 1 3 5
2 4 6
REDUCE (B, MY_MULT, DIM = 1) is [2, 12, 30] and
REDUCE (B, MY_MULT, DIM = 2) is [15, 48]."