This is automatically generated email about problems in a man page for which
you appear to be responsible. If you are not the right person or list, tell
me and I will attempt to correct my database.
See http://catb.org/~esr/doclifter/problems.html for details on how and
why these patches were generated. Feel free to email me with any questions.
Note: These patches do not change the mod date of any manual page. You
may wish to do that by hand.
Problems with LAM.7:
1. Use of low-level troff hackery to set special indents or breaks can't
be translated. The page will have rendering faults in HTML, and
probably also under third-party man page browsers such as Xman,
Rosetta, and the KDE help browser. This patch eliminates .br, .ta, .ti
and .in in favor of requests like .nf/.fi, and .RS/.RE that have
structural translations.
2. List syntax error. This means .IP, .TP or .RS/.RE markup is garbled.
This confuses doclifter, and may also mess up stricter troff
interpreters like Xman and Rosetta.
--- LAM.7-orig 2007-01-27 17:56:36.000000000 -0500
+++ LAM.7 2007-01-27 17:57:49.000000000 -0500
@@ -46,47 +46,39 @@
.SS Unloading MPI Trace Data
lamtrace(1)
.SS Reference Documents
-.HP
+.TP
"LAM/MPI Installation Guide"
-.br
included in the LAM/MPI distribution and available on
.I http://www.lam-mpi.org/
-.HP
+.TP
"LAM/MPI User's Guide"
-.br
included in the LAM/MPI distribution and available on
.I http://www.lam-mpi.org/
-.HP
+.TP
"LAM Frequently Asked Questions"
-.br
at
.I http://www.lam-mpi.org/faq/
-.HP
+.TP
"MPI Primer / Developing with LAM", Ohio Supercomputer Center
-.HP
-"MPI: A Message-Passing Interface Standard", Message-Passing
-Interface Forum, version 1.1
-.br
+.TP
+"MPI: A Message-Passing Interface Standard", Message-Passing Interface Forum, version 1.1
at
.I http://www.mpi-forum.org/
-.HP
-"MPI-2: Extensions to the Message Passing Interface", Message Passing
-Interface Forum, version 2.0
-.br
+.TP
+"MPI-2: Extensions to the Message Passing Interface", Message Passing Interface Forum, version 2.0
at
.I http://www.mpi-forum.org/
.SS MPI Quick Tutorials
-.HP
+.TP
"LAM/MPI ND User Guide / Introduction"
-.br
-at
-.I http://www.lam-mpi.org/mpi/tutorials/lam/
-.HP
+.TP
"MPI: It's Easy to Get Started"
-.HP
+.TP
"MPI: Everyday Datatypes"
-.HP
+.TP
"MPI: Everyday Collective Communication"
+at
+.I http://www.lam-mpi.org/mpi/tutorials/lam/
.SS Guaranteed Envelope Resources
.HP
"Robust MPI Message Delivery Through Guaranteed Resources",
-----------------------------
Problems with MPI.7:
1. Use of low-level troff hackery to set special indents or breaks can't
be translated. The page will have rendering faults in HTML, and
probably also under third-party man page browsers such as Xman,
Rosetta, and the KDE help browser. This patch eliminates .br, .ta, .ti
and .in in favor of requests like .nf/.fi, and .RS/.RE that have
structural translations.
2. List syntax error. This means .IP, .TP or .RS/.RE markup is garbled.
This confuses doclifter, and may also mess up stricter troff
interpreters like Xman and Rosetta.
--- MPI.7-orig 2007-01-27 17:59:59.000000000 -0500
+++ MPI.7 2007-01-27 18:00:26.000000000 -0500
@@ -142,48 +142,41 @@
.SS Unloading MPI Trace Data
lamtrace(1)
.SS Reference Documents
-.HP
+.TP
"LAM/MPI Installation Guide"
.br
included in the LAM/MPI distribution and available on
.I http://www.lam-mpi.org/
-.HP
+.TP
"LAM/MPI User's Guide"
-.br
included in the LAM/MPI distribution and available on
.I http://www.lam-mpi.org/
-.HP
+.TP
"LAM Frequently Asked Questions"
-.br
at
.I http://www.lam-mpi.org/faq/
-.HP
+.TP
"MPI Primer / Developing with LAM", Ohio Supercomputer Center
-.HP
-"MPI: A Message-Passing Interface Standard", Message-Passing
-Interface Forum, version 1.1
-.br
+.TP
+"MPI: A Message-Passing Interface Standard", Message-Passing Interface Forum, version 1.1
at
.I http://www.mpi-forum.org/
-.HP
-"MPI-2: Extensions to the Message Passing Interface", Message Passing
-Interface Forum, version 2.0
-.br
+.TP
+"MPI-2: Extensions to the Message Passing Interface", Message Passing Interface Forum, version 2.0
at
.I http://www.mpi-forum.org/
.SS MPI Quick Tutorials
-.HP
+.TP
"LAM/MPI ND User Guide / Introduction"
-.br
-at
-.I http://www.lam-mpi.org/mpi/tutorials/lam/
-.HP
+.TP
"MPI: It's Easy to Get Started"
-.HP
+.TP
"MPI: Everyday Datatypes"
-.HP
+.TP
"MPI: Everyday Collective Communication"
+at
+.I http://www.lam-mpi.org/mpi/tutorials/lam/
.SS Guaranteed Envelope Resources
-.HP
+.TP
"Robust MPI Message Delivery Through Guaranteed Resources",
MPI Developer's Conference, 1995
-----------------------------
Problems with mpirun.1:
1. SYNTAX section is actually a Unix SYNOPSIS and should be so marked.
2. Use local definitions of .EX/.EE or .DS/.DE to avoid low-level troff
requests in the page body. There are plans to add these to groff man;
in the interim, this patch adds a compatible definition to your page.
--- mpirun.1-orig 2007-01-24 12:41:08.000000000 -0500
+++ mpirun.1 2007-01-24 12:45:16.000000000 -0500
@@ -1,55 +1,47 @@
.TH MPIRUN 1 "March, 2006" "LAM 7.1.2" "LAM COMMANDS"
+.de EX
+.sp
+.nf
+.ft CW
+..
+.de EE
+.ft R
+.fi
+.sp
+..
.SH NAME
mpirun \- Run MPI programs on LAM nodes.
-.SH SYNTAX
+.SH SYNOPSIS
.hy 0
.HP
.na
mpirun
[-fhvO]
-[-c <#> | -np <#>]
-[-D | -wd <dir>]
+[-c nn | -np nn]
+[-D | -wd dir]
[-ger | -nger]
[-sigs | -nsigs]
-[-ssi <key> <value>]
+[-ssi key value]
[-nw | -w]
[-nx]
[-pty | -npty]
-[-s <node>]
+[-s node]
[-t | -toff | -ton]
[-tv]
-[-x VAR1[=VALUE1][,VAR2[=VALUE2],...]]
-[[-p <prefix_str>] [-sa | -sf]]
-[<where>]
-<program> [-- <args>]
-.PP
-.HP
+[-x settings]
+[[-p prefix_str] [-sa | -sf]]
+[where]
+{program> [-- <args>] | schema }
+
+.SH OPTION USAGE
.B Note:
Although each are individually optional, at least one of
-.IR <where> ,
+.IR where ,
.IR -np ,
or
.I -c
-must be specified in the above form (i.e., when a schema is not used).
-.PP
-.HP
-mpirun
-[-fhvO]
-[-D | -wd <dir>]
-[-ger | -nger]
-[-sigs | -nsigs]
-[-ssi <key> <value>]
-[-nw | -w]
-[-nx]
-[-pty | -npty]
-[-t | -toff | -ton]
-[-tv]
-[-x VAR1[=VALUE1][,VAR2[=VALUE2],...]]
-<schema>
-.br
+must be specified when a schema is not used.
.PP
-.HP
-.B Note:
The
.I -c2c
and
@@ -57,7 +49,6 @@
options are now obsolete. Use
.I -ssi
instead. See the "SSI" section, below.
-.RE
.ad b
.hy 1
.SH QUICK SUMMARY
@@ -178,7 +169,7 @@
exclusive with
.IR \-nsigs .
.TP
-.B -ssi <key> <value>
+.B -ssi key value
Send arguments to various SSI modules. See the "SSI" section, below.
.TP
.B -t, -ton
@@ -210,8 +201,8 @@
.IR mpirun
exits.
.TP
-.B -wd <dir>
-Change to the directory <dir> before the user's program executes.
+.BI -wd dir
+Change to the directory \fIdir\fR before the user's program executes.
Note that if the
.I -wd
option appears both on the command line and in an application schema,
@@ -220,6 +211,7 @@
.IR \-D .
.TP
.B -x
+Takes as its argument a comma-separated list of settings in the form VAR=VALUE.
Export the specified environment variables to the remote nodes before
executing the program. Existing environment variables can be
specified (see the Examples section, below), or new variable names
@@ -319,7 +311,7 @@
on nodes 0 through 3, 8 through 11, and 15. MPI_COMM_WORLD ranks will
be ordered as follows: (0, n0), (1, n1), (2, n2), (3, n3), (4, n8),
(5, n9), (6, n10), (7, n11), (8, n15).
-.PP
+.sp
Specifying by CPU is the preferred method of launching MPI jobs. The
intent is that the boot schema used with lamboot(1) will indicate how
many CPUs are available on each node, and then a single, simple
@@ -329,7 +321,7 @@
a convenience mechanism for launching on SMPs. Otherwise, the by-CPU
notation is the same as the by-node notation, except that "C" and "c"
are used instead of "N" and "n".
-.PP
+.sp
Assume in the following example that the LAM universe consists of four
4-way SMPs. So c0-3 are on n0, c4-7 are on n1, c8-11 are on n2, and
13-15 are on n3.
@@ -354,7 +346,7 @@
.I a.out
on CPUs 0 through 3, 8 through 11, and 15. MPI_COMM_WORLD ranks 0-3
will be on n0, 4-7 will be on n2, and 8 will be on n3.
-.PP
+.sp
The reason that the by-CPU nomenclature is preferred over the by-node
nomenclature is best shown through example. Consider trying to run
the first CPU example (with the same MPI_COMM_WORLD mapping) with the
@@ -365,14 +357,12 @@
the following command:
.TP 4
mpirun n0,0,0,0,1,1,1,1,2,2,2,2,3,3,3,3 a.out
-.PP
This
.IR works ,
but is definitely klunky to type. It is typically easier to use the
by-CPU notation. One might think that the following is equivalent:
.TP 4
mpirun N -np 16 a.out
-.PP
This is
.I not
equivalent because the MPI_COMM_WORLD rank mappings will be assigned
@@ -382,28 +372,27 @@
equivalent, because LAM interprets lack of a <where> as "C":
.TP 4
mpirun -np 16 a.out
-.PP
However, a "C" can tend to be more convenient, especially for
batch-queuing scripts because the exact number of processes may vary
between queue submissions. Since the batch system will determine the
final number of CPUs available, having a generic script that
effectively says "run on everything you gave me" may lead to more
portable / re-usable scripts.
-.PP
+.sp
Finally, it should be noted that specifying multiple <where> clauses
are perfectly acceptable. As such, mixing of the by-node and by-CPU
syntax is also valid, albiet typically not useful. For example:
.TP 4
mpirun C N a.out
-.PP
However, in some cases, specifying multiple <where> clauses can be
useful. Consider a parallel application where MPI_COMM_WORLD rank 0
will be a "manager" and therefore consume very few CPU cycles because
it is usually waiting for "worker" processes to return results.
Hence, it is probably desirable to run one "worker" process on all
available CPUs, and run one extra process that will be the "manager":
-.TP 4
+.EX
mpirun c0 C manager-worker-program
+.EE
.SS Application Schema or Executable Program?
To distinguish the two different forms,
.I mpirun
@@ -679,17 +668,17 @@
The
.I -ssi
switch takes two arguments:
-.I <key>
+.I key
and
-.IR <value> .
+.IR value .
The
-.I <key>
+.I key
argument generally specifies which SSI module will receive the value.
For example, the
.I <key>
"rpi" is used to select which RPI to be used for transporting MPI
messages. The
-.I <value>
+.I value
argument is the value that is passed. For example:
.TP 4
mpirun -ssi rpi lamd N foo
-----------------------------
--
Eric S. Raymond
|
