Skip to content

Commit 78dd77b

Browse files
everythingfunctionaleverythingfunctional
committed
first draft of new scan intrinsics
1 parent 996a8b9 commit 78dd77b

File tree

1 file changed

+364
-0
lines changed

1 file changed

+364
-0
lines changed

‎proposals/scan/scan.txt

Lines changed: 364 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,364 @@
1+
To: J3 J3/##-###
2+
From: Brad Richardson
3+
Subject: SCAN_INCLUSIVE and SCAN_EXCLUSIVE
4+
Date: 06-Jan-2023
5+
6+
#Reference:
7+
8+
Introduction
9+
============
10+
11+
SCAN is a common operation closely related to REDUCE. Both SCAN and
12+
REDUCE apply a binary operation to a sequence. SCAN returns the
13+
sequence of results of the operations, where REDUCE returns only the
14+
final result. Whether a SCAN is INCLUSIVE or EXCLUSIVE determines
15+
whether an element in the resulting sequence includes the result of
16+
the binary operation with the corresponding element in the input
17+
sequence or not, respectively.
18+
19+
Typical applications that make us of scan operations include
20+
design of binary adders, polynomial interpolation, simulation of
21+
parallel algorithms that assume the ability for multiple processors
22+
to access the same memory cell at the same time, on parallel machines
23+
that forbid simultaneous access. Additional applications can be found
24+
on the Wikipedia page for "Prefix sum":
25+
https://en.wikipedia.org/wiki/Prefix_sum
26+
27+
Proposal
28+
========
29+
30+
Provide SCAN_INCLUSIVE and SCAN_EXCLUSIVE intrinsic functions and
31+
CO_SCAN_INCLUSIVE and CO_SCAN_EXCLUSIVE collective subroutines. These
32+
functions and subroutines shall implement inclusive and exclusive
33+
scan operations analogous to the REDUCE function and CO_REDUCE
34+
subroutine.
35+
36+
Descriptions
37+
============
38+
39+
SCAN_INCLUSIVE(ARRAY, OPERATION[, MASK, ORDERED]) or
40+
SCAN_INCLUSIVE(ARRAY, OPERATION, DIM[, ORDERED])
41+
42+
Description. Generalized inclusive scan of an array.
43+
44+
Class. Transformational function
45+
46+
Arguments.
47+
ARRAY shall be an array of any type.
48+
OPERATION shall be a pure function with exactly two arguments; each
49+
argument shall be a scalar, nonallocatable, nonpointer,
50+
nonpolymorphic, nonoptional dummy data object with the same
51+
declared type and type parameters as ARRAY. If one argument
52+
has the ASYNCHRONOUS, TARGET, or VALUE attribute, the other
53+
shall have that attribute. Its result shall be a
54+
nonpolymorphic scalar and have the same declared type and
55+
type parameters as ARRAY. OPERATION should implement a
56+
mathematically associative operation. It need not be
57+
commutative.
58+
DIM shall be an integer scalar with a value in the range
59+
1 <= DIM <= n, where n is the rank of ARRAY.
60+
MASK (optional) shall be of type logical and shall be conformable
61+
with ARRAY.
62+
ORDERED (optional) shall be a logical scalar.
63+
64+
Result Characteristics. The result is of the same declared type and
65+
type parameters as ARRAY. If DIM is present, it has the same rank and
66+
shape as ARRAY, otherwise it has rank 1. If MASK is present and an
67+
array, the result has the size of the number of .true. elements in
68+
MASK. If Mask is present and a scalar with the value .false., the
69+
result has size 0. If MASK is present and a scalar with the value
70+
.true., or is not present, the result has size equal to the size of
71+
ARRAY.
72+
73+
Result Value.
74+
Case (i): The result of SCAN_INCLUSIVE(ARRAY, OPERATION[, ORDERED])
75+
has values obtained by applying OPERATION to the previous
76+
element in the result and the corresponding element in
77+
ARRAY, taken in array element order. The first element
78+
has the value of the first element in ARRAY. If ORDERED
79+
is present with the value true, the values of the
80+
elements of the result are calculated in array element
81+
order.
82+
Case (ii): The result of
83+
SCAN_INCLUSIVE(ARRAY, OPERATION, MASK = MASK[, ORDERED])
84+
is as for Case (i) except that the sequence is only for
85+
those elements of ARRAY for which the corresponding
86+
elements of MASK are true. I.e.
87+
SCAN_INCLUSIVE(ARRAY,
88+
OPERATION,
89+
MASK = MASK[,
90+
ORDERED]) ==
91+
SCAN_INCLUSIVE(PACK(ARRAY, MASK=MASK),
92+
OPERATION[,
93+
ORDERED]).
94+
Case (iii): If ARRAY has rank one,
95+
SCAN_INCLUSIVE(ARRAY, OPERATION, DIM = DIM[, ORDERED])
96+
has a value equal to that of
97+
SCAN_INCLUSIVE(ARRAY, OPERATION[, ORDERED]). Otherwise,
98+
the values of the section
99+
(s1, s2, ..., sDIM-1, :, sDIM+1, ..., sn) of
100+
SCAN_INCLUSIVE(ARRAY, OPERATION, DIM = DIM[, ORDERED])
101+
are equal to
102+
SCAN_INCLUSIVE(ARRAY(s1,
103+
s2,
104+
...,
105+
sDIM-1,
106+
:,
107+
sDIM+1,
108+
...,
109+
sn),
110+
OPERATION[,
111+
ORDERED])
112+
113+
Examples. The following examples all use the function MY_MULT, which
114+
returns the product of its two integer arguments.
115+
Case (i): The value of SCAN_INCLUSIVE([1, 2, 3], MY_MULT)
116+
is [1, 2, 6].
117+
Case (ii): If B is the array [1, 2, 3, 4], the value of
118+
SCAN_INCLUSIVE(B, MY_MULT, MASK = mod(B, 2)==0) is
119+
[2, 8].
120+
| 1 2 3 |
121+
Case (iii): If C is the array | 4 5 6 |,
122+
| 7 8 9 |
123+
| 1 2 3 |
124+
SCAN_INCLUSIVE(C, MY_MULT, DIM=1) is | 4 10 18 |,
125+
| 28 80 162 |
126+
| 1 2 6 |
127+
and SCAN_INCLUSIVE(C, MY_MULT, DIM=2) is | 4 20 120 |.
128+
| 7 56 504 |
129+
130+
131+
SCAN_EXCLUSIVE(ARRAY, OPERATION, IDENTITY[, MASK, ORDERED]) or
132+
SCAN_EXCLUSIVE(ARRAY, OPERATION, IDENTITY, DIM[, ORDERED])
133+
134+
Description. Generalized exclusive scan of an array.
135+
136+
Class. Transformational function
137+
138+
Arguments.
139+
ARRAY shall be an array of any type.
140+
OPERATION shall be a pure function with exactly two arguments; each
141+
argument shall be a scalar, nonallocatable, nonpointer,
142+
nonpolymorphic, nonoptional dummy data object with the same
143+
declared type and type parameters as ARRAY. If one argument
144+
has the ASYNCHRONOUS, TARGET, or VALUE attribute, the other
145+
shall have that attribute. Its result shall be a
146+
nonpolymorphic scalar and have the same declared type and
147+
type parameters as ARRAY. OPERATION should implement a
148+
mathematically associative operation. It need not be
149+
commutative.
150+
IDENTITY shall be a scalar with the same declared type and type
151+
parameters as ARRAY.
152+
DIM shall be an integer scalar with a value in the range
153+
1 <= DIM <= n, where n is the rank of ARRAY
154+
MASK (optional) shall be of type logical and shall be conformable
155+
with ARRAY
156+
ORDERED (optional) shall be a logical scalar.
157+
158+
Result Characteristics. The result is of the same declared type and
159+
type parameters as ARRAY. If DIM is present, it has the same rank and
160+
shape as ARRAY, otherwise it has rank 1. If MASK is present and an
161+
array, the result has the size of the number of .true. elements in
162+
MASK. If Mask is present and a scalar with the value .false., the
163+
result has size 0. If MASK is present and a scalar with the value
164+
.true., or is not present, the result has size equal to the size of
165+
ARRAY.
166+
167+
Result Value.
168+
Case (i): The result of
169+
SCAN_EXCLUSIVE(ARRAY, OPERATION, IDENTITY[, ORDERED]) has
170+
values obtained by applying OPERATION to the previous
171+
element in the result and the corresponding previous
172+
element in ARRAY, taken in array element order. The first
173+
element has the value IDENTITY. If ORDERED is present with
174+
the value true, the values of the elements of the result
175+
are calculated in array element order.
176+
Case (ii): The result of
177+
SCAN_EXCLUSIVE(ARRAY, OPERATION, IDENTITY, MASK = MASK[,
178+
ORDERED]) is as for Case (i) except that the sequence is
179+
only for those elements of ARRAY for which the
180+
corresponding elements of MASK are true. I.e.
181+
SCAN_EXCLUSIVE(ARRAY,
182+
OPERATION,
183+
IDENTITY,
184+
MASK = MASK[,
185+
ORDERED]) ==
186+
SCAN_EXCLUSIVE(PACK(ARRAY, MASK=MASK),
187+
OPERATION,
188+
IDENTITY[,
189+
ORDERED]).
190+
Case (iii): If ARRAY has rank one,
191+
SCAN_EXCLUSIVE(ARRAY,
192+
OPERATION,
193+
IDENTITY,
194+
DIM = DIM[,
195+
ORDERED])
196+
has a value equal to that of
197+
SCAN_EXCLUSIVE(ARRAY,
198+
OPERATION,
199+
IDENTITY[,
200+
ORDERED]).
201+
Otherwise, the values of the section
202+
(s1, s2, ..., sDIM-1, :, sDIM+1, ..., sn) of
203+
SCAN_EXCLUSIVE(ARRAY,
204+
OPERATION,
205+
IDENTITY,
206+
DIM = DIM[,
207+
ORDERED])
208+
are equal to
209+
SCAN_EXCLUSIVE(ARRAY(s1,
210+
s2,
211+
...,
212+
sDIM-1,
213+
:,
214+
sDIM+1,
215+
...,
216+
sn),
217+
OPERATION,
218+
IDENTITY[,
219+
ORDERED])
220+
221+
Examples. The following examples all use the function MY_MULT, which
222+
returns the product of its two integer arguments.
223+
Case (i): The value of SCAN_EXCLUSIVE([1, 2, 3], MY_MULT, 1) is
224+
[1, 1, 2].
225+
Case (ii): If B is the array [1, 2, 3, 4], the value of
226+
SCAN_EXCLUSIVE(B, MY_MULT, 1, MASK = mod(B, 2)==0) is
227+
[1, 2].
228+
| 1 2 3 |
229+
Case (iii): If C is the array | 4 5 6 |,
230+
| 7 8 9 |
231+
| 1 1 1 |
232+
SCAN_EXCLUSIVE(C, MY_MULT, 1, DIM=1) is | 1 2 3 |,
233+
| 4 10 18 |
234+
| 1 1 2 |
235+
and SCAN_EXCLUSIVE(C, MY_MULT, 1, DIM=2) is | 1 4 20 |.
236+
| 1 7 56 |
237+
238+
NOTE X
239+
If OPERATION is not computationally associative, SCAN_INCLUSIVE and
240+
SCAN_EXCLUSIVE without ORDERED=.TRUE. with the same argument values
241+
might not always produce the same result, as the processor can apply
242+
the associative law to the evaluation.
243+
244+
245+
CO_SCAN_INCLUSIVE(A, OPERATION[, STAT, ERRMSG])
246+
247+
Description. Generalized inclusive scan across images.
248+
249+
Class. Collective subroutine.
250+
251+
Arguments.
252+
A shall not be polymorphic. It shall have the same shape,
253+
type, and type parameter values in corresponding
254+
references. It shall not be a coindexed object. It is an
255+
INTENT(INOUT) argument. If A is scalar, the computed value
256+
is the result of the inclusive scan operation of applying
257+
OPERATION to the values of A in all corresponding
258+
references. If A is an array, each element of the computed
259+
value is equal to the result of the scan operation of
260+
applying OPERATION to corresponding elements of A in all
261+
corresponding references.
262+
263+
The value assigned to an element of A is the element of the
264+
computed result corresponding to the image number of the
265+
executing image.
266+
OPERATION shall be a pure function with exactly two arguments; the
267+
result and each argument shall be a scalar, nonallocatable,
268+
nonpointer, nonpolymorphic data object with the same type
269+
and type parameters as A. The arguments shall not be
270+
optional. If one argument has the ASYNCHRONOUS, TARGET, or
271+
VALUE attribute, the other shall have that attribute.
272+
OPERATION shall implement a mathematically associative
273+
operation. OPERATION shall be the same function on all
274+
images in the corresponding references.
275+
276+
The computed values of an inclusive scan operation over a
277+
set of values are obtained by applying OPERATION to the
278+
previous element in the result and the value from the
279+
corresponding image. The value on image 1 is unchanged.
280+
STAT (optional) shall be a noncoindexed integer scalar with a decimal
281+
exponent range of at least four. It is an INTENT(OUT)
282+
argument.
283+
ERRMSG (optional) shall be a noncoindexed default scalar. It is an
284+
INTENT(INOUT) argument.
285+
286+
The semantics of STAT and ERRMSG are described in 16.6.
287+
288+
Example. If the function MY_MULT returns the product of its two
289+
integer arguments, the number of images in the current team is two,
290+
and A is the array [1, 3, 5] on image 1, and [2, 4, 6] on image 2,
291+
the value of A after executing the statement
292+
CALL CO_SCAN_INCLUSIVE(A, MY_MULT)
293+
is [1, 3, 5] on image 1, and [2, 12, 30] on image 2.
294+
295+
296+
CO_SCAN_EXCLUSIVE(A, OPERATION, IDENTITY[, STAT, ERRMSG])
297+
298+
Description. Generalized exclusive scan across images.
299+
300+
Class. Collective subroutine.
301+
302+
Arguments.
303+
A shall not be polymorphic. It shall have the same shape,
304+
type, and type parameter values in corresponding references.
305+
It shall not be a coindexed object. It is an INTENT(INOUT)
306+
argument. If A is scalar, the computed value is the result
307+
of the exclusive scan operation of applying OPERATION to the
308+
values of A in all corresponding references. If A is an
309+
array, each element of the computed value is equal to the
310+
result of the scan operation of applying OPERATION to
311+
corresponding elements of A in all corresponding references.
312+
313+
The value assigned to an element of A is the element of the
314+
computed result corresponding to the image number of the
315+
executing image.
316+
OPERATION shall be a pure function with exactly two arguments; the
317+
result and each argument shall be a scalar, nonallocatable,
318+
nonpointer, nonpolymorphic data object with the same type
319+
and type parameters as A. The arguments shall not be
320+
optional. If one argument has the ASYNCHRONOUS, TARGET, or
321+
VALUE attribute, the other shall have that attribute.
322+
OPERATION shall implement a mathematically associative
323+
operation. OPERATION shall be the same function on all
324+
images in the corresponding references.
325+
326+
The computed values of an exclusive scan operation over a
327+
set of values are obtained by applying OPERATION to the
328+
previous element in the result and the value from the
329+
corresponding previous image. The value on image 1 is
330+
IDENTITY.
331+
IDENTITY shall be a scalar with the same declared type and type
332+
parameters as ARRAY. It shall not be a coindexed object. Its
333+
value shall be the same in all corresponding references.
334+
STAT (optional) shall be a noncoindexed integer scalar with a decimal
335+
exponent range of at least four. It is an INTENT(OUT)
336+
argument.
337+
ERRMSG (optional) shall be a noncoindexed default scalar. It is an
338+
INTENT(INOUT) argument.
339+
340+
The semantics of STAT and ERRMSG are described in 16.6.
341+
342+
Example. If the function MY_MULT returns the product of its two
343+
integer arguments, the number of images in the current team is three,
344+
and A is the array [1, 3, 5] on image 1, [2, 4, 6] on image 2,
345+
and [7, 8, 9] on image 3, the value of A after executing the statement
346+
CALL CO_SCAN_EXCLUSIVE(A, MY_MULT, 1)
347+
is [1, 1, 1] on image 1, [1, 3, 5] on image 2,
348+
and [2, 12, 30] on image 3.
349+
350+
NOTE X
351+
If the OPERATION function is not mathematically commutative, the result
352+
of calling CO_SCAN_INCLUSIVE or CO_SCAN_EXCLUSIVE can depend on the order
353+
of evaluations.
354+
355+
Straw Vote
356+
==========
357+
358+
How should SCAN be spelled?
359+
360+
A. SCAN_INCLUSIVE and SCAN_EXCLUSIVE
361+
B. INCLUSIVE_SCAN and EXCLUSIVE_SCAN
362+
C. PREFIX_SUM and POSTFIX_SUM
363+
D. INSCAN and EXSCAN
364+
E. Other

0 commit comments

Comments
 (0)