
README

Version of July 29, 1993 - Steve Otto, Oregon Graduate Institute

This README file describes characteristics of the Message Passing Interface
Report Document.  Specifically it covers:

- the structure of the directory "mpi-report",

- how to add a chapter to the report, 

- the LaTeX labels used in the document, 

- documentation on the mpi macros



Directory Structure
-------------------

Following is a list of the files in the directory mpi-report, and 
their purposes:

  README - this file
  CLEANUP - a script that deletes working files created by LaTeX, 
     backup files, etc., and leaves just the appropriate source files  
  MAKE-MPI-REPORT - a script that runs LaTeX three times to get the 
     table of contents and page numbers correct (the first run may 
     generate LaTeX Warnings that references are undefined - these 
     go away in the second run), xdvi to run an X-windows .dvi
     previewer, then runs dvips to produce a 
     postscript file from the dvi file.
  mpi-report.tex - the top-level LaTeX file.  It includes all of the other 
     necessary .tex files
  MAKE-MPI-CHAPTER - a script similar to MAKE-MPI-REPORT. It takes 
     one argument, the filename of the chapter to be produced.  It 
     uses the file chapter-head.tex and a set of 
     temporary files named temp.*
  chapter-head.tex - a file which when followed by 
     a single chapter followed by "\end{document}" is a freestanding 
     LaTeX file that can produce a printout of a single chapter
  mpi-macs.tex - LaTeX macros for the document.
  credits.tex - the acknowledgements chapter
  intro.tex - the introduction chapter
  terms.tex - the terms and conventions chapter
  pt2pt.tex - the point to point communications chapter
  coll.tex - the collective communications chapter
  topol.tex - the topologies chapter
  lang.tex - the language bindings chapter
  correct.tex - the correctness issues chapter
  inquiry.tex - the environmental management and inquiry chapter
  prof.tex - the profile chapter
  context.tex - the context chapter
  iis.tex - the initial implementation subset chapter
  refs.bib - the .bib file containing references
  appTop.tex - an annex containing man pages for topology functions


Adding a Chapter
----------------

To add a chapter, create a tex file named foo.tex, where "foo" is 
descriptive of the chapter's contents.  The first few lines of 
the file should look similar to:

  %foo.tex
  %Version of July 14, 1992

  \chapter{Chapter Title}
  \label{chap:foo}

At the appropriate place in the file mpi-report.tex put the line

  \include{foo}


At the apropriate place in the file README (this file) put a brief 
description of the chapter.


LaTeX Labels used
-----------------

Following are the (current) LaTeX label usages in the various files:


appTop.tex:\label{app:Top}
coll.tex:\label{sec:coll}
coll.tex:\label{chap:coll}
coll.tex:\label{sec:coll-barrier}
coll.tex:\label{fig:collcom}
coll.tex:%\label{fig}
coll.tex:\label{subsec:coll-broadcast}
coll.tex:\label{subsec:coll-gather}
coll.tex:\label{subsec:coll-scatter}
coll.tex:\label{subsec:coll-allcast}
coll.tex:\label{subsec:coll-alltoall}
coll.tex:\label{subsec:coll-reduce}
coll.tex:\label{subsec:coll-scan}
context.tex:\label{sec:context}
context.tex:\label{chap:context}
context.tex:\label{sec:predef-groups}.
context.tex:\label{sec:predef-comms}
context.tex:\label{context-ex1}
context.tex:\label{context-ex2}
context.tex:\label{context-ex3}
context.tex:\label{context-ex4}
context.tex:\label{context-ex5}
context.tex:\label{context-ex6}
correct.tex:\label{sec:formal}
correct.tex:\label{chap:formal}
correct.tex:\label{chap:correct}
correct.tex:\label{sec:correct}
iis.tex:\label{sec:subset}
iis.tex:\label{chap:subset}
iis.tex:\label{sec:iis}
iis.tex:\label{chap:iis}
inquiry.tex:\label{sec:inquiry}
inquiry.tex:\label{chap:inquiry}
intro.tex:\label{sec:intro}
intro.tex:\label{chap:intro}
lang.tex:\label{sec:lang}
lang.tex:\label{chap:lang}
lang.tex:\label{chap:binding}
lang.tex:\label{nomatch}
prof.tex:\label{sec:prof}
prof.tex:\label{chap:prof}
pt2pt.tex:\label{sec:pt2pt}
pt2pt.tex:\label{chap:pt2pt}
pt2pt.tex:\label{sec:pt2pt-intro}
pt2pt.tex:\label{sec:pt2pt-basicsend}
pt2pt.tex:\label{subsec:pt2pt-messagedata}
pt2pt.tex:\label{subsec:pt2pt-envelope}
pt2pt.tex:\label{sec:pt2pt-basicreceive}
pt2pt.tex:\label{subsec:pt2pt-status}
pt2pt.tex:\label{sec:pt2pt-semantics}
pt2pt.tex:\label{sec:pt2pt-typematch}
pt2pt.tex:\label{sec:pt2pt-conversion}
pt2pt.tex:\label{sec:pt2pt-modes}
pt2pt.tex:\label{sec:pt2pt-nonblock}
pt2pt.tex:\label{subsec:pt2pt-commobject}
pt2pt.tex:\label{subsec:pt2pt-commstart}
pt2pt.tex:\label{subsec:pt2pt-commend}
pt2pt.tex:\label{subsec:pt2pt-multiple}
pt2pt.tex:\label{sec:pt2pt-probe}
pt2pt.tex:\label{sec:pt2pt-persistent}
pt2pt.tex:\label{sec:pt2pt-sendrecv}
pt2pt.tex:\label{sec:pt2pt-nullproc}
pt2pt.tex:\label{sec:pt2pt-datatype}
pt2pt.tex:\label{eq:pt2pt-extent}
pt2pt.tex:\label{eq:pt2pt-type1}
pt2pt.tex:\label{subsec:pt2pt-datatypeconst}
pt2pt.tex:\label{subsec:pt2pt-addfunc}
pt2pt.tex:\label{subsec:pt2pt-datatypeuse}
pt2pt.tex:\label{subsec:pt2pt-examples}
pt2pt.tex:\label{subsec:pt2pt-segmented}
terms.tex:\label{chap:terms}
terms.tex:\label{sec:terms}
topol.tex:\label{sec:topol}
topol.tex:\label{chap:topol}
topol.tex:\label{poisson}


LaTeX Macros
------------

	I've started to do some work on defining LaTeX macros
for mpi constants, mpi functions, mpi function definitions, C function
definitions, etc.  We are separating out the macros into several
different LaTeX macros so as to facilitate the creation of indices.
For example, when it comes time to create an index to all the C function
bindings that appear in the draft, we can modify the \cfuncdef macro
so as to help us create the index.  For this reason, it is important
for all of us to start using the macros consistently.

	Note: I've only made a start at this, and the macros no doubt
have flaws.  I'm interested in your feedback.

	Here is what I have so far.

\func or \mpifunc
		These are synonyms for the same macro.  They are used
		to refer to mpi functions in normal text, when the
		abstract, language independent function is meant.
		\func takes one argument: the name of the function.

		Example usage from coll.tex:
		\func{MPI\_GATHERC} behaves like \func{MPI\_GATHER} 
		restricted to contiguous buffers, and with the additional ...

		Note: the macro that was called \mpifunc is now: \mpifuncold

\cfunc
		Just like \func, but used when one is referring to the C
		binding.
		Example usage:
		\cfunc{ mpiBcastc( buffer, len, type, root, comm )}
\ffunc
		Just like \func, but used when one is referring to the Fortran
		binding.
\mpiarg		
		Use this to refer to (language independent) function
		arguments in normal text.
		Eg:
		\mpiarg{array\_of\_handles}
\carg		
		Just like \mpiarg, but for C functions.
		Eg:
		\carg{count}
\farg		
		Just like \mpiarg, but for Fortran functions.
		Eg:
		\farg{count}
\type		
		Use this to refer to the type of (language independent) function
		arguments in normal text.
		Eg:
		\type{MPI_INTEGER}
\ctype
		Just like \type, but for C types.
		Eg:
		\ctype{double}
\ftype
		Just like \type, but for Fortran types.
		Eg:
		\ftype{INTEGER}
\const
		Use this to refer to mpi-defined constants, in a language-indep
		way.  Takes one arg, the name of the constant.
		Eg:
		\const{MPI_MINLOC}
\cconst
		like \const, but for the C name of the constant
		Eg:
		\const{mpi_int}
\fconst
		like \const, but for the Fortran name of the constant
		Eg:
		\const{MPI_INTEGER}
\IN, \OUT, \INOUT
		Macros for our "IN", "OUT", "INOUT" types.

\begin{funcdef}
\end{funcdef}
\funcarg
		The function definition environment. Language-indep version.
		\begin{funcdef} takes one additional argument, like this:

		\begin{funcdef}{MPI\_BCAST( bd\_handle, root, comm )}

		The argument is the function and arg list that we are defining.
		\end{funcdef} terminates the environment and takes no arguments.
		funcdef is basically a list environment, but instead of
		\item's inside, one says \funcarg.  \funcarg takes three
		arguments, like this:

		\funcarg{\IN}{root}{rank of broadcast root}

		The three arguments are: datatype of arg, name of arg, and an
		English description of what the arg is about.  \funcarg
		typesets these three quantities in different ways.

		So here is a complete funcdef taken from coll.tex:

\begin{funcdef}{MPI\_BCAST( bd\_handle, root, comm )}
\funcarg{\INOUT}{bd\_handle}{Handle to buffer descriptor.  On root, this is the send buffer descriptor, elsewhere, this is the receive buffer descriptor.}
\funcarg{\IN}{root}{rank of broadcast root}
\funcarg{\IN}{comm}{communicator handle}
\end{funcdef}
		

\begin{cfuncdef}
\end{cfuncdef}
\cfuncarg
		Just like funcdef environment, but for the C binding.

		here is a cfuncdef from coll.tex:

\begin{cfuncdef}{mpiBcast( bd, root, comm )}
\cfuncarg{BuffDesc}{bd}{Buffer descriptor.  On root, this is the send buffer descriptor, elsewhere, this is the receive buffer descriptor.}
\cfuncarg{int}{root}{rank of broadcast root}
\cfuncarg{Communicator}{comm}{communicator}
\end{cfuncdef}

		NOTE that I have started to make some language binding
		choices!  "BuffDesc" is a typedef to a C buffer-descriptor
		handle.  Another thing we need to start doing is to
		get a single list of all our names for things.

		By the way, I personally cannot stand "MPI_" preceding
		all variable types. It's ugly, and I note that 
		the X window system, for example, does not precede all 
		type names with an "X".  Occasionally they do, but not
		always.  All function names, however, are preceded
		by "X" or "Xt".  Therefore, I propose that all MPI
		function names begin with "mpi" in C, "MPI_" in Fortran,
		but that type names, such as "BuffDesc", do not.

		MPI-defined constants probably do need to start with
		"mpi_" and "MPI_" or else we really will have too many 
		collisions with user programs.  End of editorial.

\begin{ffuncdef}
\end{ffuncdef}
\ffuncarg
		Just like funcdef environment, but for the Fortran binding.

		here is a ffuncdef from coll.tex:

\begin{ffuncdef}{MPI\_BCAST( bd, root, comm )}
\ffuncarg{INTEGER}{bd}{Index of Buffer descriptor.  On root, this is the send buffer descriptor, elsewhere, this is the receive buffer descriptor.}
\ffuncarg{INTEGER}{root}{rank of broadcast root}
\ffuncarg{INTEGER}{comm}{index of communicator}
\end{ffuncdef}

\begin{constlist}
\end{constlist}
\constitem
		An environment for displaying lists of mpi constants.
		Usage:

\begin{constlist}
\constitem{MPI\_MAX}{ maximum}
\constitem{MPI\_MIN}{ minimum}
\constitem{MPI\_SUM}{ sum}
\constitem{MPI\_PROD}{ product}
\constitem{MPI\_AND}{ and (logical or bit-wise integer)}
\constitem{MPI\_OR}{ or (logical or bit-wise integer)}
\constitem{MPI\_XOR}{ xor (logical or bit-wise integer)}
\constitem{MPI\_MAXLOC}{ maximum value and rank of process with maximum value
(rank of first process with maximum value, in case of ties)}
\constitem{MPI\_MINLOC}{ minimum value and rank of process with minimum value
(rank of first process with minimum value, in case of ties)}
\end{constlist}

		Note that \begin{constlist} takes no arguments, and that
		\constitem takes two arguments.  I guess I don't have the
		C and Fortran versions of these yet.

