[Mpi-21] Comments on merged MPI-2.1 document (as per March meeting)

[Jesper Larsson Traeff]

Dear All,

here are my belated comments to the merged MPI 1.2/PI 2.0 document as
per of the Chicago Forum. Hope they are still useful, perhaps to the
chapter editors. A lot of the typos and suggestions apply also to the
already passed MPI 1.3 and MPI 2.1 documents, which I'm afraid are
finalized now? Especially in the parts concerning the "old", "MPI-1"
functionality, there is, in my opinion, quite a lot to be done for the
document to work, as was also discussed at the meeting (deprecation of
deprecated functions, C++ bindings, MPI-1.2 <-> MPI-2 contradictions,
...). In addition to what has been said, it would be good if some of
us could take the time to make sure the examples are correct,
effective (in getting the point across - some are very long, and
somewhat hurried), and do not use deprecated functionality (there's a
remark on p.25 that the examples have not been checked and verified -
do we want this?). Now that this merge is being done, I think it is
important that it will be done well, and we should take the time for
this.

Best regards

Jesper

Two general consistency things:
0.
count, rank, tag - should be "(nonnegative integer)" in all interface specs
(in one-sided it is usually so, in pt2pt sometimes so, sometimes just 
"(integer)"
1.
Is is "high quality" or "high-quality"?

ii, 15: 
[TYPO]: documnts -> documents

Chapter 1:
[COMM]: In general all the contrasting of MPI-1/MPI-2 reads very
awkward. Eg. Section 1.2 should be completely eliminated.
p.1,l.28 [TYPO]: "[8,7]" -> "[7,8]" (refs in ascending order)
p.3,l.16 [TYPO]: Ref to Chapter 3 is wrong
p.4,l.13 [SUGG]: Drop "With this version of MPI..."
p.5,l.26 [TYPO]: Capitalize \textit{send} -> \textit{Send}
p.6,l.1 [SUGG]: "remove" -> "complement"
p.7,l.27 [ADD]: Reference to Appendix of Deprecated Functions (as discussed
at Forum meeting)
p.7,l.29 [TYPE]: repeats line 26, drop
p.6,l.35ff [COMM]: The things of JOD that are now in the standard should be
removed from this discussion.

Chapter 2:
p.9,l.16 [SUGG]: Eliminate MPI-1/MPI-2 distinctions, e.g. "MPI Terms and 
Conventions Chapter"
p.12,l.29 [SUGG]: Make a reference to definition of typemap (Section 3.12, 
p.75)
p.14,l.36 [SUGG]: shouldn't "inquery function" be "query function"?
p.16,l.24 [TYPO]: "principle" -> "principal"
p.22,l.23 [TYPO]: "a MIMD style" -> "an MIMD style" (?)
p.25,l.9 [QUESTION]: Do we really want to stand by this, that the examples
have "not been carefully checked or verified"???

Chapter 3:
[SUGG]: Change the examples (p.27; 3.2, 3.3, 3.4 etc.) such that they'll work
for any number of processes, eg. make explicit what both ranks do 

if (myrank == 0) {
...
} else if (myrank == 1) {
...
}

At least, examples should be consistent, some of the Fortran examples 
(as in 3.6) mention what rank .EQ. 1 does
[SUGG]: for count, rank, tag arguments, change "(integer)" to
"(nonnegative integer)" in all functions descriptions. At least, it
should be consistent, which ii now not the case

p.27,l.21 [SUGG]: shouldn't this be "Example 3.1"?
p.28,l.5 [SUGG]: "(myrank ==1)" reads badly, since it is not in the
example; make an explicit if-clause (see above)
p.28,l.29 [COMM]: here count is "(nonnegative integer)", but this
disappears later, eg. in RECV, p.32,l.4
p.28,l.33,34 [SUGG]: change "(integer)" to "(nonnegative integer)" for
dest and tag arguments (and throughout)
p.29, Tables should contain all (MPI-1 and MPI-2) datatypes. 
p.30 [SLIP]: MPI_LONG_LONG has disappeared
p.46,l.28 [QUESTION]: Does the Forum realy want to stand to this 
(recommendation, almost, of unsafe programming style)??
p.53,l.29 [SLIP]: drop this line "Section on Argument and register 
optimization" (similar is elsewhere, seems an edition slip, eg. p.72,l.32)
p.54,l.15: take line up after "("
p.58,l.29-30: state explicitly that count is a "(nonnegative integer)".
Same in all array_of_request functions
p.59,l.35 [QUESTION]: or is it intended that WAITSOME/TESTSOME takes
an array of atleast one request?
p.71,l.7-8: change font of MPI_ANY_SOURCE to sf
p.76,l.39 [SUGG]: "New Datatype ..." -> "Additional Datatype..."
p.87,l.1,2,11 [TYPO]: n-dimensional -> $n$-dimensional (or other consistent
font)
p.94,l.22: replace deprecated MPI_Address by MPI_Get_address
p.94,l.45 [TYPO]: refs are wrong
p.97,l.2 [SUGG]: for "gather" put forward reference to Chapter 4
p.99,l.32 [TYPO]: "a argument" -> "an argument"
p.103,l.32 [SUGG]: "ELSE" -> "ELSE IF (rank.EQ.1)"
p.107,l29 [SUGG]: This example (3.36) could be broken up into smaller
examples
p.117,l.22 [SUGG]: change
"else /* myrank == 1 */"
into the explicit
"else if (myrank == 1)"
(general suggestion)
p.117,l.41 [TYPO]: concatenate all -> concatenates all

Chapter 4: This chapter does not work in the merged form.
p.121,l.48 [TYPO]: "Such processes are called the root" -> "Such a process
is called the root"
p.125,l.3 [TYPO]: MPI_Exscan is missing
p.125,l.35 [TYPO]: drop this line on MPI_Alltoallw
p.125,l.47 [SUGG]: "additions" is not the right word here (whole section is
VERY problematic, as is this whole chapter)
p.127,l.2 [SUGG]: "being identical" must be rephrased
p.128,l.19 [SUGG]: all count arguments explicitly "(nonnegative integer)"
p.132,l.82 [TYPO]: left justify closing "}"
p.135,l.40 [TYPO]: "that that" -> "that"
p.144,l.43 [TYPO]: "The jth block of data sent" -> "The block of data sent"
p.151,l.27 [SUGG]: "and a scan (parallel prefix) operation." -> "and
two scan (parallel prefix) operations."
p.152,l.38 [TYPO]: join lines up
p.153,l.5-6 [TYPO]: remove ''
p.153,l.20 [SUGG]: include MPI_EXSCAN
p.153,l.33-34 [SUGG]: "xor" -> "exclusive or"
p.153,l.43ff [TYPO]: format table properly
p.159,l.160 [SUGG]: add MPI_EXSCAN to list
p.160,l.34 [TYPO]: "len" in sf font
p.161,l.20ff [TYPO]: RECV, SEND -> MPI_Recv, MPI_Send + add MPI_Comm_size/rank
calls to example to set groupsize and rank variables
p.161,l.35 [TYPO]: group-size -> groupsize
p.163,l.15 [TYPO]: "MPI includes variants..." -> "MPI includes a variant of
the reduce operation"
p.163,l.45ff [TYPO]: description of MPI_IN_PLACE has been corrected?
p.164,l.31 [TYPO]: "MPI includes variants..." -> "MPI includes a variant
of the reduce operation..."
p.166,l.14ff [SUGG]: drop this rationale, since MPI_EXSCAN has now been
included
p.166,l.28 [TYPO]: drop
p.170,l.22 [COMMENT]: In my opinion, this example is NOT correct (the 
second scenario may hang, process 1 can enter the Bcast which cannot
complete before process 2 enters Bcast, which it cannot before the Send
has completed - as in example 4.25)

Chapter 5: This chapter does not work in the merged form. [SUGG]: since
the chapter deals also with caching on windows and other objects, change
title to
"Groups, contexts, and caching"
p.175,l.18 [SUGG]: "dealt with so far"... is no longer true
p.175,l.38-39 [SUGG]: obviously drop lines on no collectives on intercomms
p.177,l.10 [SUGG]: drop parenthetical remark
p.177,l.19 [SUGG]: drop ref to next chapter
p.184,l.22-23 [QUESTION]: Is this advice to implementers needed anymore?
p.184,l.46-47 [SUGG]: drop parenthetical remark
p.186,l.20-22 [SUGG]: drop, obviously
p.190,l.26 [QUESTION]: parenthetical remarks seems strange, drop?
p.193,l.7 [TYPO]: "the debugging" -> "a debugging"
p.199,l.28 [SUGG]: "the above examples is really three examples" - why not
split? The example is too long
p.200,l.28 [TYPO]: drop "Advice to users:" (twice)
p.200,l.48 [TYPO]: Obviously drop
p.201,l.19 [SUGG]: "A group is represented" -> "A group can be represented"
p.201,l.38 [QUESTION]: what does "the same algorithm is appropriate..." mean?
p.205, Exsample 1 [SUGG]: very long...
p.208,l.22 [TYPO]: remove blank space, line tags up. Example is excessively 
long!
p.212,l.44 [SUGG]: "you" does not read well, "one can" or sth.
p.212,l.45 [SUGG]: the other extreme would be not to allow it at all...
p.213,l.8 [TYPO]: "attributes are attached to communicators" is now wrong
p.213,l.23 [TYPO]: represents -> requires
p.217,l.40 [TYPO]: formatting, move lines up
p.219,l.46 [TYPO]: "the the" -> "then the"

Chapter 6:
p.231,l.47 [SUGG]: remove "tremendous"
p.232,l.17 [SUGG]: remove PARMACS rationale, seems obsolete nowadays
p.233,l.19 [SUGG]: remove EXPRESS/PARMACS rationale

Chapter 7:
p.249,l.5 [SUGG]: "for C" -> "for C and C++"
p.261-262 [SUGG]: move MPI-2 errir classes into running discussion/tables

Chapter 8: [SUGG] Rename chapter to
"Controlling the functionality: The info object"
or something like this. Any better/good suggestions?
p.271,l.14 [SUGG]: Remove this line
p.274,l.36 [TYPO]: change font in (key,value) to sf. Also elsewhere
p.275,l.5 [TYPO]: font
p.276,l.37 [TYPO]: font should be $n$th

Chapter 9:
p.279,l.21ff [TYPO]: Remove/reformulate this historical/anecdotical remark

Chapter 10:
p.312,l.15 [COMM]: Note that here it is said that counts are "(nonnegative
integers)"; same should be done also for p2p and collectives, also for
consistency reasons.
p.313,l.29,l.32 [QUESTION]: is it "high quality" or "high-quality"?
p.315,l.11 [TYPO]: MPI_TYPE_EXTENT -> MPI_TYPE_GET_EXTENT (also in next
examples)
p.330,l.10 [QUESTION]: what is the state of Fortran compilers at this time
of writing?

Chapter 11:

Chapter 12:
p.432,l.27 [SUGG]: 
Make reference to subarray constructor definition, 3.12.4, p.86

Chapter 13:
p.435,l.24 [SUGG]: modify, only "MPI"
p.436,l.13 [SUGG]: "as of writing" - this state of affairs has changed

Chapter 14:
p.482,l.27 [SUGG]: Section 14.6 can be dropped?