Subject: hpff-doc: Comments on Library

From: [email-masked]
Date: Wed, 17 Jul 96 12:43:10 EDT

---------------------------------------------------------------------------
[email-masked] is a mailing list for HPF 2.0 language specification
authors and editors.  Instructions for adding or deleting yourself from this
list appear at the bottom of this message.
---------------------------------------------------------------------------

Rob,

These are the suggested corrections or changes that I didn't get
to hand to you in hard copy before you left the meeting last week.
I'm using the same page numbers as the copy distributed there.

In what follows I suggest changes to GRADE_UP/DOWN to reflect the decision
that it should return one-based values. I also indicate where DYNAMIC
could be deleted from the minimal, standard version of the inquiry
functions, to reflect the changed status of the DYNAMIC attribute as an
approved extension. None of the other suggested changes are substantive
ones.

I have one general question on terminology that is used through the current
HPF specifications.  Why is PRODUCT(SHAPE(...)) used instead of SIZE(...)?
Should I avoid using SIZE too in the descriptions of SORT_UP/DOWN? It just
seems bulkier to me, but I'm perfectly willing to be stylistically
consistent, I just wondered what the technical reason for this might be. I
guess you can say PRODUCT(SHAPE(<scalar>) is 1, since SHAPE(<scalar>) is a
rank 1, size 0 array, while SIZE(<scalar>) is undefined. That's the only
difference I can think of, and the contexts where I used SIZE were never
scalar.

--Carol

**************
Sect. 5.2, p. 88
l. 4 from b.: 
    replace
	"of he system inquiry functions NUMBER_OF_PROCESORS and"
    with 
	"of the system inquiry functions NUMBER_OF_PROCESORS or"

**************
Sect. 5.4.3 Array Reduction Functions, p. 90
ll. 18-19 refer to "binary operations IAND, IOR, IEOR, and .NEQV."
and then talks about "XXX reduction...where XXX is one of the binary
operators above." For consistency, then, I recommend
l. 4 from b.:
    replace
	"identity element for PARITY is .FALSE."
    with
	"identity element for .NEQV. is .FALSE."
(although the meaning is clear).

**************
Sect. 5.4.4 Array Combining Scatter Functions, p. 91

ll. 5-6 reads
	"These functions all have the form 
	XXX_SCATTER(ARRAY, BASE, INDX1, ..., INDXn, MASK)"

Since the following paragraphs clarify that the actual argument lists
vary somewhat, depending on the operation XXX, it would be more accurate
to replace this with something like
	"These functions have the general form ... except in
	the special cases noted below"

**************
Sect. 5.4.5 Array Prefix and Suffix Functions, p. 92

ll. 19-21 reads
	"The functions all have the form 
	XXX_PREFIX(ARRAY, DIM, MASK, SEGMENT, EXCLUSIVE)
	XXX_SUFFIX(ARRAY, DIM, MASK, SEGMENT, EXCLUSIVE)"

Just as above, it would be more accurate to replace this with something like
	"These functions have the general form ... except in
	the special cases noted below."

**************
Sect. 5.5.3 Mapping inquiry subroutines, p. 97
ll. 6-12 from b.
	I suggest reordering HPF_DISTRIBUTION and HPF_TEMPLATE
	alphabetically for consistency with rest of list.

For the same reason, I'd also reorder Section 5.7.16 and 5.7.17 on 
pp. 115-119, since HPF_DISTRIBUTION and HPF_TEMPLATE are the only two 
routines not in correct alphabetical order in pp. 100-141, and it makes 
them more awkward to look up.

**************
Sect. 5.5.6 Array combining scatter functions, p. 98
ll. 15-16 
    Replace
	"COUNT_SCATTER(ARRAY, BASE, INDX1, ..., INDXn, MASK)"
    with
	"COUNT_SCATTER(MASK, BASE, INDX1, ..., INDXn)"
 
ll. 23-24 Delete redundant spec. for IALL_SCATTER (following IPARITY...)

**************
Sect. 5.7.7 COPY_PREFIX, p. 107
l. 3 from b.
    Optionally, one could add a comment to the effect that
	"[by the rules stated Section 5.4.5].  Note that this set of values
	is never empty."

**************
Sect. 5.7.9 COPY_SUFFIX, p. 109
l. 8
    Optionally, one could add a comment to the effect that
	"[by the rules stated Section 5.4.5]. Note that this set of values
	is never empty."

**************
Sect. 5.7.13 GRADE_DOWN(ARRAY,DIM), p. 111
ll. 3-4 
    Suggested replacement for
	"Description. Produces a permutation of the indices of an array..."
    is
	"Description. Produces a permutation of the indices of an array,
	expressed as one-based coordinates,..."

l. 7
    Add to "must be of type integer, real, or character." the note
	"It must not be scalar."  (I think this is necessary for 
	consistency with the description "...the indices of an array.")

l. 16 (Case (i))
    Replace
	"S = GRADE_DOWN(ARRAY)"
    with
	"S = GRADE_DOWN(ARRAY)+SPREAD(LBOUND(ARRAY),DIM=2,NCOPIES=SIZE(ARRAY))-1"
    (Check this! It's longish but based on the way MAXLOC/MINLOC are described.)
p
    And, if there's some good reason for the lengthier form, "SIZE(ARRAY)"
    could be replaced throughout by the even longer "PRODUCT(SHAPE(ARRAY))" 
    (or vice versa, if there isn't).

l. 18 (Case (i), cont.)
    Question:  Why is "SIZE(B,1)" used instead of "SIZE(B)"? 
    (They are equivalent, so I guess it's another stylistic question,
     unless SIZE(B,1) is considered easier to compute or to understand?
     I just think it's clearer to without the dimension argument)

l. 25 (Case (ii))
    Replace
	"S = GRADE_DOWN(ARRAY,DIM=K)"
    with
	"S = GRADE_DOWN(ARRAY,DIM=K) + LBOUND(ARRAY,DIM=K) - 1"

l. 29-30 
    It is still correct, with the above indicated minimal change, to say that
	"R(i1,i2,...,:,...,in) is a permutation of all the integers in
	the range LBOUND(ARRAY,K):UBOUND(ARRAY,K)." 
    But you may want to introduce another variable above, say 
	G = GRADE_DOWN(ARRAY,DIM=K), with R = G + LBOUND(ARRAY,DIM=K) - 1, 
    and substitute, for greater clarity and directness, that
	"G(i1,i2,...,:,...,in) is a permutation of all the integers
	in the range 1:SIZE(ARRAY,K)."

**************
Sect. 5.7.14 GRADE_UP(ARRAY,DIM), p. 112
	IDENTICAL TO CHANGES FOR GRADE_DOWN (except for line and page numbers)
ll. 9-10
    Suggested replacement for
	"Description. Produces a permutation of the indices of an array..."
    is
	"Description. Produces a permutation of the indices of an array,
	expressed as one-based coordinates,..."

l. 13
    Add to "must be of type integer, real, or character." the note
	"It must not be scalar."  (I think this is necessary for 
	consistency with the description "...the indices of an array.")

l. 22 (Case (i))
    Replace
	"S = GRADE_UP(ARRAY)"
    with
	"S = GRADE_UP(ARRAY)+SPREAD(LBOUND(ARRAY),DIM=2,NCOPIES=SIZE(ARRAY))-1"
    (Check this! It's roundabout but based on the way MAXLOC/MINLOC are described.)

    And, if there's some good reason for the lengthier form, "SIZE(ARRAY)"
    could be replaced throughout by the wordier "PRODUCT(SHAPE(ARRAY))" 
    (or vice versa, if there isn't).

l. 24 (Case (i), cont.)
    Question:  Why is "SIZE(B,1)" used instead of "SIZE(B)"? 
    (They are equivalent, so I guess it's another stylistic question,
     unless SIZE(B,1) is considered easier to compute or to understand?
     I just think it's clearer to without the dimension argument)

l. 31 (Case (ii))
    Replace
	"S = GRADE_UP(ARRAY,DIM=K)"
    with
	"S = GRADE_UP(ARRAY,DIM=K)+LBOUND(ARRAY,DIM=K)-1"

l. 35-36 
    It is still correct, with the above indicated minimal change, to say that
	"R(i1,i2,...,:,...,in) is a permutation of all the integers in
	the range LBOUND(ARRAY,K):UBOUND(ARRAY,K)." 
    But you may want to introduce another variable above, say 
	G = GRADE_UP(ARRAY,DIM=K), with R = G + LBOUND(ARRAY,DIM=K) - 1, 
    and substitute, for greater clarity and directness, that
	"G(i1,i2,...,:,...,in) is a permutation of all the integers
	in the range 1:SIZE(ARRAY,K)."

**************
Sect. 5.7.15, HPF_ALIGNMENT, pp. 113-115
l.17 on p. 113, ll. 7-11 on p. 114, and table in middle of p. 115
    Remove "DYNAMIC" argument from this description, and add to
    "Approved extensions" version instead.

**************
Sect. 5.7.16, HPF_TEMPLATE, pp. 115-117
l. 3 from b.
    Close up space in "AXIS_ INFO" to "AXIS_INFO".

l. 3 from b. on p. 115, ll. 13-15 from b. plus bottom line (table) on p. 117
    Remove "DYNAMIC" argument from list of args, description of args, and
    table of results. Add to "Approved extensions" version instead.

**************
Sect. 5.7.17, HPF_DISTRIBUTION, pp. 118
l. 2
    Close up space in "PROCESSORS_ RANK" to "PROCESSORS_RANK".

**************
Sect. 5.7.46 SORT_DOWN, pp. 137-138
l. 7 from b. on p. 137
    Add to "must be of type integer, real, or character." the note
	"It must not be scalar."  

ll. 1-12 on p. 138
    It would be more consistent with surrounding style with fewer blanks
	around arguments.
    Also, if PRODUCT(SHAPE(ARRAY)) is really preferred to SIZE(ARRAY),
	that replacement could be made here.
	
************** 
Sect. 5.7.47 SORT_UP, p. 138-139
bottom line of p. 138
    Add to "must be of type integer, real, or character." the note
	"It must not be scalar."  

ll. 8-18 on p. 139
    It would be more consistent with surrounding style with fewer blanks
	around arguments.
    Also, if PRODUCT(SHAPE(ARRAY)) is really preferred to SIZE(ARRAY),
	that replacement could be made here.
			
---------------------------------------------------------------------------
To (un)subscribe to this list, send mail to [email-masked].
Leave the subject line blank, and in the body put the line
(un)subscribe <email-address>
---------------------------------------------------------------------------