MPI Forum Editorial Changes
Bill Gropp went through the entire MPI Standard and came up with this list of issues that should be addressed to generate a high quality standard document. Because of the wide range in scope of these issues, the MPI Forum needs to help decide how each of these issues should be treated. Please indicate your preference for each of these issues below.
Sign in to Google to save your progress. Learn more
Issue: 161 - Throughout - What is the formatting for the data-representations, such as "external32" and "native"? Does it include the double quotes? What is the font? Are these all indexed (they could be \const values)? Not all uses include the double quotes.
Use \const{"external32"}
Issue: 162 - Throughout - Tables 14.1 and 14.2 shows a different version of a list of constants with short descriptions. Should we use this uniformly? Contrast with the datatype list in 14.3, and the one on page 660 in chapter 18.
Issue: 163 - Throughout - What is the format for "Fortran 2008 TS 29113"? Is there a + (page 639 doesn't use one)? Is it F2008+TS 29113?
Check with MPI Fortran committee
Issue: 164 - Throughout - Use mpiterm = value, not mpiterm == value, to express the cases where mpiterm has the value "value".
Edit to update
Issue: 165 - Throughout - Throughout, \const is often used where \error, \errormain, and related macros should be used (to properly index the terms).
Edit to update
Issue: 166 - Section 16.1.3, Table 16.2 - p. 634 - The replacements here are not datatypes. This caption is incorrect.
Change the caption to "Removed MPI-1 datatypes. The indicated routine may be used for changing the lower and upper bound respectively."
Issue: 167 - Section 3.3.2 - p. 38 - "sent by a C or C++ process - I don't know what a "C process" is and I think that the natural interpretation (main written in C) isn't even correct - since it really refers to the language binding used for the specific call that sends the message, e.g., in a program with a C main program but one that calls a library, written in Fortran, that makes MPI calls.
Change "sent by a C of C++ process" to be specific - "sent from a routine using the MPI C language interface" Same for the "Fortran process" in that same sentence.
Issue: 168 - Section 12.4.3 - p. 515 - The text about "argc and argv is optional" is incorrect - the arguments are required, but the values may be NULL. This should be compared with MPI_Init and both made consistent and correct. Specifically, this textIn C, the passing of argc and argv is optional, as with MPI_INIT as discussed in Section 8.7. In C, null pointers may be passed in their place.should use the same text as for MPI_INIT:
Change to "The version for ISO C accepts the argc and argv that are provided by the arguments to main or NULL."
Issue: 169 - Section 13.4.1 - p. 535 - The MPI equivalents are MPI_FILE_READ ..." is *incorrect*. The MPI routines have different semantics than the POSIX routines. Equivalent is the wrong term.
Instead, "The MPI routines to read from and write to a file are …"
Issue: 170 - Section 13.7 - p. 584 - This says that error handlers are inherited from MPI_COMM_WORLD. Didn't this change to MPI_COMM_SELF (see 8.3)? Also see the rationale on the same page.
Change MPI_COMM_WORLD to MPI_COMM_SELF for these references
Issue: 171 - Section 4.1.1 - p. 87 - INTEGER*8 is not a Fortran type. It is a common extension; this should be acknowledged.
Add a footnote after "these arguments" with text "This assumes that the Fortran 77 system accepts the common extension of "INTEGER*8" for 8 byte integers."
Issue: 172 - p. 104 - Example 4.8 uses "sizeofreal" without defining it - it is pretty obvious, but making it clear that it is sizeof(REAL) would be better. This could use the new Fortran SIZEOF operator (storage_size).
Update the example to use Fortran operator, or use MPI_TYPE_GET_EXTENT as in Example 4.13 and elsewhere
Issue: 173 - Section 11.2.3 - p. 435 - Font for "size" and for i in "process i"
size is \mpicode and process $i$ should use math mode
Issue: 174 - Section 13.2.8 - p. 528 - font for info in "Hints specified via info"
Issue: 175 - Section 18.1.20 - p. 681 - Why are examples 18.5ff at the end of the chapter?
Editor to figure this out
Issue: 176 - p. 386 - MPI_INITIALIZED needs (logical) for flag
Suggest asking the bindings committee to review
Issue: 177 - p. 387 - MPI_ABORT needs the arg types (e.g., (handle))
Suggest asking the bindings committee to review
Issue: 178 - p. 439 - MPI_WIN_ATTACH - the base and size arguments need (choice) and (non-negative integer) respectively
Suggest asking the bindings committee to review
Issue: 179 - p. 440 - MPI_WIN_DETACH - the base argument needs (choice)
Suggest asking the bindings committee to review
Issue: 180 - p. 690 - MPI_STATUS_F2F08 and MPI_STATUS_F082F need the types for the arguments, e.g., (Status) or something like that.
Suggest asking the bindings committee to review
Issue: 181 - Section 8.7 - p. 382 - for the argv info key, "argv Space separated arguments to command". What if the arguments contain spaces? Is there an escape for spaces? Is this case just not handled?
Suggest adding "If an argument contains a space, there is no way to tell from the value of the argv info key whether a space is part of the argument or is separating different arguments."
Issue: 182 - Section 5.12.4 - p. 206 - MPI_ISCATTERV. Are the descriptions of sendcounts and displs consistent with other expressions.
Issue: 183 - Section 1.12 - p. 6 - What is not included in the standard, dates from 1.0. In particular, the "time constraint". Further, this section would benefit from having text about relying on existing practice as much as feasible.
Edit to update
Issue: 184 - Section 1.13 - p. 8 - At the end of that section, there is text on the JOD. This is now even more out-of-date. It also doesn't mention any other documents, such as the MPIR docs. It should note that the JOD hasn't been updated since MPI-2.0.
Edit to update that the JOD dates from MPI-2 and that this material is mentioned mostly as historical background on the development of the standard
Issue: 185 - Section 1.13 - p. 8 - Re-write the last item that starts "Several Index pages..." to be specific about the indices, and to provide links as in the other items in this list.
Edit to update
Issue: 186 - Section 3.2.4 - p. 31 - The (However, it is unsafe...) does not need the parenthesis.
Remove the parenthesis
Issue: 187 - Section 3.3.2 - p. 38 - Index XDR
Edit to update
Issue: 188 - Section 3.5 - p. 45 - Example 3.9 is an erroneous example but you have to read it carefully to know that. It would be better if, like some other erroneous examples, it had a comment to that effect within the example.
Edit to update
Issue: 189 - Section 3.7.4 - p. 58 - Section 3.7.4, index progress.
Edit to update
Issue: 190 - Section 3.7.5 - p. 60 - The inline of MPI_WAIT(&array_of_request[i], ...) in the description of MPI_WAITANY should (a) be a display and (b) address the C-bias of this code. Similarly for TESTANY and WAITALL
Edit to use language independent version and display mode. An alternative is to write in C and/or Fortran, and make that clear.
Issue: 191 - Section 4.1.4 - p. 101 - r[i] should probably be \code{r[i]}, since it refers to code. Or should this be an mpicodeblock? Ditto for cyclic()
Edit to update, using code (since examples are in C)
Issue: 192 - Section 5.1 - p. 144 - Consider adding collective semantics to the index (semantics!collective communications)
Edit to update
Issue: 193 - Section 5.1 - p. 146 - Index "hidden" communicator
Edit to update (also page 237, 472)
Issue: 194 - Section 5.12 - p. 199 - Section 5,12, progression rules. index progress.
Edit to update
Issue: 195 - Multiple occurances - p. 218 - API is used without definition, and only used occasionally. A consistent term should be used for the MPI specification, and used consistently.
Add to chapter 2?
Issue: 196 - Section 6.2.4 - p. 248 - Host process in the section on 6.2.4. What is a host process? Probably need to remove that. Also, remove or change the "machine dependant absolute address" as applied to MPI_COMM_WORLD. See also 8.1.
Chapter committee to update
Issue: 197 - Section 7.5.7 - p. 332 - In 7.5.7, Example 7.8 is mixed C and language independent - it needs to be either all C or all language independent. To make language independent, it should use mpicodeblock environment, and not have a ';' at the end of the call.
Make language independent
Issue: 198 - Section 7.6.1 - p. 336 - Unnumbered example on page 336 uses "l" (ell) as a variable - this is hard to distinguish from "1" (one). Suggest using a different variable
Suggest using k instead of l (ell), since previous loop uses k. Alternative is to use m and n for the two loops
Issue: 199 - Section 7.6.1 and 7.6.2 - p. 338 - Process \mpicode{j} and $j$ are used in different paragraphs. One is in a math context and the other is a code context, but it is jarring.
Since the "j" in "proocess j" is not in the code, use math mode for it in 7.6.1.
Issue: 200 - Section 7.6.2 - p. 341 - Is recvcounts[l] (in sans-serif) recvcounts[ell] or recvcounts[one]? ell should not be used as an index (or most any other) variable. Similar problems in other sections (e.g., 7.6.1)
Suggest using k instead of l (ell), since previous loop uses k. Alternative is to use m and n for the two loops.
Issue: 201 - Section 8.1.2 - p. 361 - MPI_HOST - is this obsolete? What exactly does this mean? We should deprecate.
Chapter committee to update
Issue: 202 - Section 8.2 - p. 365 - Index cray pointers. Check whether gfortran (a) supports cray pointers and (b) needs -fcray-pointer (Note that 6.3.0 accepts that without complaint).
Edit to update
Issue: 203 - Section 8.4 - p. 374 - Why not alphabetize the error classes in table 8.1 and 8.2?
Edit to update
Issue: 204 - Section 8.8 - p. 391 - Example 8.14/8.15 and surrounding text refers to RS/6000 and Sun workstations. This is archaic text.
Remove references to particular system names
Issue: 205 - Chapter 10 througout; see POE page 404 - p. 399 - Chapter 10: Old, unexpanded acronyms and terms (e.g., MPP) and very old software (e.g., IBM POE) should be updated (history is fine, but should clearly be in a historical context).
Update text by expanding acronyms and making historical refs clearly historical
Issue: 206 - Section 10.1 - p. 399 - 10.1 Is the extensive reference to PVM still relevant?
Chapter committee to update
Issue: 207 - Section 11.1 - p. 430 - 11.1, At the end. What font(s) should be used for destination=target etc?
Edit to use \mpicode
Issue: 208 - Section 11.5 - p. 466 - "billboard" should be "bulletin board" ? plus add a reference.
Change to bulletin board
Issue: 209 - Section 11.5 - p. 466 - Review font choice for post, start, complete, wait. Should these be mpicode?
use \mpicode for post/start/complete/wait
Issue: 210 - Section 11.5.5 - p. 478 - Inconsistent (on the same page!) "bit-vector OR" "bit vector or"; note "bit-vector \texttt{IOR}" (so should OR be in \code{OR}?)
Change to use \code{OR}
Issue: 211 - Section 11.8 - p. 496 - Examples 11.20 looks different than other examples that show two (or more) processes (e.g., Example 11.18). These should have the same style.
Edit Example 11.18 to use "Process B…:" and add text to that example explaining the format: "In the following, "Process B…" means any other process besides process A, and is used where multiple processes may execute the code in that column."
Issue: 212 - Example 11.21 - p. 497 - Add the missing ":" and delete the blank line after the process names to match other use in this chapter
Edit to update
Issue: 213 - Section 13.2.1 - p. 522 - Do we still use "Fortran 90" (page 522)? More generally, how do we refer to Fortran, esp with TS29113.
Change all uses of Fortran 90 to "Fortran" or "Fortran + TS29113" if that TS is required. Refer only to Fortran 77 if that standard is required, or to a particular version of Fortran (as officially adopted).
Issue: 214 - Section 13.2.5 - p. 526 - Instead of "expensive", use "time consuming"?
Update as suggested
Issue: 215 - Section 13.6.3 - p. 577 - Section 13.6.3, index progress
Edit to update
Issue: 216 - Section 13.6.10 - p. 579 - Index "size changing" (note italics - should this be bold?)
Edit to update
Issue: 217 - Section 13.8 - p. 584 - "can be converted into the error classes" - this is not really correct; the correct statement is that the error class can be extracted from the error code. Should compare with Error Class discussion for RMA or MPI-1. More generally, some chapters have an explicit section on I/O Error Classes, and others do not. Should the document be more consistent about this, particularly for classes that are really primarily for operations described in that chapter?
For this sentence and the one after it "In addition, calls …" , replace with: "Each implementation dependent error code returned by the I/O routines belongs to either one of the error classes in Table 13.5 or one of the other MPI error classes." . The more general question requires Forum discussion.
Issue: 218 - Section 17.1 - p. 635 - Under backward incompatibilities, comm_dup (and comm_idup?) no longer propopates info hints.
Update text
Issue: 219 - Section 18.1.10 - p. 664 - "new MPI-2 functions" drop the "new"
Update as suggested
Issue: 220 - Section 18.1.16 - p. 671 - Rather than name the sections at the end of this section, make sure to use links.
Use link in the bullet that begins "to minimize the burden..." for the sections, rather than there names. Where these are not sections (e.g., paragraph headings), change the text appropriately.
Issue: 221 - Section 18.1.17 - p. 674 - What font should be used in paragraph titles for ASYNCHRONOUS, MPI_F_SYNC_REG
Suggest using the same font as for other Fortran code (\texttt). See all paragraph entries in 18.1.17
Issue: 222 - Section 18.2.3 - p. 686 - "same answer" can't be taken literally - logical values aren't required to be the same in every language.
Add after "… same error handlers.": "In the above, 'same answer' means same truth value - the representation of true and false may be different in different languages."
Issue: 223 - Annex B - p. 843 - The change log has inappropriate entries (see #11, "Like MPI_PROBE..." The change log should *only* point out the change, not provide more information about it.
Chapter committee to update
Issue: 224 - Annex B - p. 850 - A particularly egrigious example of a bad entry, #8 includes an advice to implementors (!!!)
Chapter committee to update
Issue: 225 - Bibliography - p. 858 - Reference 42, the URL for www.nag.co.uk/sc22wg5 is no longer available (I get a "Forbidden: You don't have permission to access this resource."); the same is true for the ftp site. We may need to refer to the official version at https://www.iso.org/standard/45136.html , even though this is not freely available.
Change to the iso.org reference
Issue: 226 - General Index - p. 860 - General Index. Better explain "Bold face numbers mark section titles"
TBD
Issue: 227 - MPI Constant Index - p. 868 - In constant index, add text that the underlined entries are the "primary" definitions
Add "Underlined page numbers give the location of the primary definition or use of the indexed term."
Issue: 228 - Multiple occurances - Examples. Some do not have titles, others do (instead, beginning with text). Do we care? Example 7.1 consists solely of a table. There should be a short description, at least. Example 11.5 starts with code. There should be a short description. Example 14,1 starts with code. Example 14.2 starts with code. Example 14.3 starts with code. Example 18.12 starts with code Example 18.13 starts with code Example 18.14 starts with 4 parts; it needs an intro to the parts. Ditto 18.15
Chapter committee to update
Issue: 229 - Multiple occurances - The example environment is not used consistently. See, for example, 6.5.1, "Example #1a" - this should be \begin{example} .... . This continues into 6.5.2, 6.5.3, 6.5.4 (which should *not* be a separate section - "Example #4" is a terrible section title. 6.5.5 ditto. 6.5.6 ditto. 6.6.3 has another "Example 1", "Example 2". 10.4.6 (several places). Section 6.7.6 has an attributes example, but does not use the example environment. Page 580, section 13.6.11 also has examples without the environment. Page 584, section 13.9.1 ditto. Also 13.9.2. Page 658, after MPI_Type_create_f90_integer, no example environment. Page 662, ditto.
Update to use the example environment in all cases, and to correctly use the \label and \ref commands in the LaTeX source. Update section title for 6.5.4 to "Communication Safety Example"
Issue: 230 - Multiple occurances - Is it inter-communicator or intercommunicator? (See section titles for 6.2.3, 6.2.4
Use intercommunicator and (also intracommunicator)
Issue: 231 - Multiple occurances - Is it non-blocking or nonblocking? Is non-blocking preferred?
Use non-blocking
Issue: 232 - Multiple occurances - Check uses of which and correct to ", which" or "that"
Update to use which and that as appropriate
Issue: 233 - Multiple occurances - Should PVM and similar items be indexed?
Yes, and index in the general index
Issue: 234 - Multiple occurances - Consider adding progress to index. Insure mpi, mpif.h, mpi_f08 in the correct font in the index.
Add progress to index; update font for Fortran include/modules.
Issue: 235 - Throughout - Some of the index entries in the examples index are much too long.
Propose updates to the chapter committee (primarily tools)
Issue: 236 - Throughout - Index thread-safe; Index Threads!POSIX and POSIX threads
Edit to update
Issue: 237 - Throughout - Index all (relevant) references to semantics of operations. See, e.g., page 523.
Edit to update
Issue: 238 - Throughout - Index TS29113
Edit to update
Issue: 239 - Throughout - In constant and predefined handle index, many entries do not have a "primary" entry (where the item is first defined; other entries should be where used).
Find relevant entry; could enlist chapter committees
Issue: 240 - Throughout - What is the punctuation for Examples, as in "Example 8.5 The following code is correct(i.e., is there anything after the number (e.g., 8.5:) or the phrase (e.g., is it ...correct or ...correct:)
Edit all to have a period after the example number.
Issue: 241 - Throughout - In use of \paragraph{...}, should the item end with a period, as in \paragraph{The \mpiarg{maxprocs} argument.}? Some do and some don't. Also, should \paragraph or \paragraph* be used?
Edit to end with a period, and to always use \paragraph*
Issue: 242 - Throughout - In use of the description environment, should the items be \item[foo]textor \item[foo] --- text(the latter is used in section 11.2.1). In 13.2, a : (colon) is usedinstead of the ---. More generally, there is no consistency in the use of description-like environments. See, for example,Page 42 (in advice to implementors, e.g., ready send: ....)Page 97, MPI_ORDER_C etc.Page 268, MPI_COMM_TYPE_SHARED - this type ...Page 269, the list starting mpi_assert_no_any_tag (boolean, default:false). Note also that all descriptions of info keys and valid valuesshould follow the same format (which they do not now).Page 315, the list of topology information is an enumerate within anitemize (!) - e.g., 1. ndims (number of dimensions) ...Page 361, MPI_TAG_UB etc. Then note the very different formatting *onthe same page* for Tag Values, Host Rank, etc.Page 366, MPI_ERRORS_ARE_FATAL etc.Page 383, "command Name of program ... "Page 404, "The argv argument " ...Page 429, Section 11.1. "Remote write: ..." (this *might* be ok)Page 432, no_locks etc. Notes these are info keys; see the verydifferent list on page 269.Page 443, MPI_WIN_FLAVOR_CREATE ...Page 464, active target communication etc. An itemize *may* beappropriate here.Page 479, MPI_MOD_NOCHECK etc. - these are asserts, but should be in aconsistent description environment.Page 484, fence: etc.Page 522, MPI_MODE_RDONLY etc.Page 530, "access_style (comma ...)" Use consistent format for infoitems. Also note here that "integer" means "integer expressed as astring"Page 549, MPI_SEEK_SET etc.Page 555, The same MPI_SEEK_SET list.Page 610, MPI_T_PVAR_CLASS_STATE etc.
Update to use \item[foo]text consistently, and to use for all so lists.
Issue: 243 - Throughout - A macro is needed for the INTERFACE blocks, such as those for INTERFACE MPI_WIN_ALLOCAE_SHARED to ensure uniformity (see page 434 and others)
Need to coordinate with pythonization
Issue: 244 - Throughout - Erroneous examples. See the example on page 581, section 13.6. This example is clearly marked as erroneous. Should all such examples be marked in the same way?
Mark all erroneous examples as the example on 581: /* ---------------- THIS EXAMPLE IS ERRONEOUS --------------- */ (or the Fortran equivalent)
Issue: 245 - Throughout - Various. In text, "INTEGER(KIND=...)" and "INTEGER (KIND=...)" are used (and sometimes with a ~ for the space). Pick one and use consistently. Also be consistent in the examples.
Use "INTEGER(KIND=…)" to avoid line breaking between INTEGER and (KIND=…)
Issue: 246 - Throughout - Some chapters use bold for emphasis and new terms, others do not. See, for example, "connected" on page 425 in 10.5.4.
Edit to use proper term macros; search for use of emph
Issue: 247 - Section 5.12.8 - p. 210 - MPI_IALLTOALLV. Note the misalignment of the arg "request" - this is because of bogus spaces in the LaTeX for these. See also MPI_IREDUCE.
Check that pythonization fixes these
Issue: 248 - Section 13.5 - p. 536 - Under Coordination. This text predates the addition of nonblocking collective routine and needs to be corrected.
Issue: 249 - Throughout - Do we use MPI_FUNC(all args) in text, or just MPI_FUNC? Section 3.8 uses MPI_IMPROBE(source, tag, ...)
Need to discuss with chapter authors
Issue: 250 - Chapter 2 - p. 12 - Semantic terms. The group of terms between "predefined" and "equivalent" only describe these terms with respect to datatypes. There are other predefined values (e.g., MPI_COMM_WORLD), and equivalent objects (e.g., Groups).
Add "The following terms apply to MPI datatypes" before "predefined".
Issue: 251 - Section 2.10 - p. 22 - We could mention that we do endeavor to check the examples, e.g., that they at least compile.
Add "Many of the examples have been compiled by tools that extract the examples from the source files for the MPI Standard."
Issue: 252 - Section 3.2.2 - p. 27 - The list of MPI datatypes that correspond to REAL*2 etc. should note that REAL*2 etc. are obsolete extensions to the Fortran standard, and are provided for convenience. Users should take advantage of the "KIND" versions and related MPI routines.
Add a footnote after "additional data types" : These types, such as DOUBLE COMPLEX and INTEGER*4, are not standard Fortran but are common extensions to Fortran."
Issue: 253 - Section 3.8.3 - p. 73 - The "as if a receive from MPI_PROC_NULL..." is odd language and should be improved.
Issue: 254 - Example 4.17 - p. 128 - In the comment "... the following may be safer" it would be clearer to add "than the above". Or, since the code is creating a new type, it might be better to say:
/* Since the compiler may pad the structure, it is best to explicitly set the size of the MPI datatype for a structure element. We do this with MPI_Type_create_resized */
Issue: 255 - Example 4.19 - p. 132 - Example 4.19 uses the variable "i" both to get an address (as an MPI_Aint) and as a loop index. This really should use different variables; I recommend using "ubase" or "ubaseadd" for the address. It also uses a variable "mpi_utype" which violates the rule of avoiding "MPI_" prefixes. This case is actually allowed, but may suggest to the reader that other, global, symbols can start with "mpi_".
Edit example as suggested
Issue: 256 - Section 5.1 - p. 143 - Chapter 5, section 5.1. This text is out of date because it doesn't mention the persistent collectives, but does enumerate all of the other collective routines. It would benefit from some introductory text before launching into barrier/ibarrier etc. It is also a bit misleading for intercommunicator collectives.
Chapter committee to update
Issue: 257 - Section 5.1 - p. 144 - On the second page, there is the statement "This statement excludes, of course, the barrier operation.". However, in the context where this is placed, there are other collectives which are synchronizing by their semantics (not just their implementation), e.g., Allreduce and Alltoall. As such, this text is misleading. A fix is to mention routines that are semantically synchronizing, and give a few examples without providing a complete list.
Simplest is to add "and other routines whose semantics imply synchronization."