xenial (1) mpiexec.lam.1.gz

Provided by: lam-runtime_7.1.4-3.1_amd64 bug

NAME

       mpiexec - Run MPI programs on LAM nodes.

SYNOPSIS

       mpiexec [global_args] local_args1 [: local_args2 [...]]

       mpiexec [global_args] -configfile filename

OPTIONS

       Global  arguments  apply to all commands that will be launched by mpiexec.  They come at the beginning of
       the command line.

       -boot     Boot the LAM run-time environment before running the  MPI  program.   If  -machinefile  is  not
                 specified,  use  the  default  boot  schema.   When  the MPI processes finish, the LAM run-time
                 environment will be shut down.

       -boot-args args
                 Pass arguments to the back-end lamboot command  when  booting  the  LAM  run-time  environment.
                 Implies -boot.

       -d        Enable lots of debugging output.  Implies -v.

       -machinefile hostfile
                 Enable  "one  shot"  MPI  executions;  boot  the  LAM run-time environment with the boot schema
                 specified by hostfile (see bhost(5)), run the MPI program, and then shut down the LAM  run-time
                 environment.  Implies -boot.

       -prefix lam/install/path
                 Use the LAM installation specified in /lam/install/path/.  Not compatible with LAM/MPI versions
                 prior to 7.1.

       -ssi key value
                 Set the SSI parameter key to the value value.

       -tv       Launch the MPI processes under the TotalView debugger.

       -v        Be verbose

       One or more sets of local arguments must be specified (or a config file;  see  below).   Local  arguments
       essentially  include  everything allowed in an appschema(5) as well as the following options specified by
       the MPI-2 standard (note that the options listed below must be specified before appschema arguments):

       -n numprocs
                 Number of copies of the process to start.

       -host hostname
                 Specify the hostname to start the MPI process on.  The  hostname  must  be  resolvable  by  the
                 lamnodes command after the LAM run-time environment is booted (see lamnodes(1)).

       -arch architecture
                 Specify  the  architecture  to start the MPI process on.  mpiexec essentially uses the provided
                 architecture as a pattern match against the output of the  GNU  config.guess  utility  on  each
                 machine in the LAM run-time environment.  Any subset will match.  See EXAMPLES, below.

       -wdir directory
                 Set the working directory of the executable.

       -soft     Not yet supported.

       -path     Not yet supported.

       -file     Not yet supported.

       other_arguments
                 When  mpiexec  first  encounters an argument that it doesn't recognize (such as an appschema(5)
                 argument, or the MPI executable name), the remainder of the arguments will be  passed  back  to
                 mpirun  to  actually start the process.  As such, all of mpiexec's arguments that are described
                 above must come before appschema arguments and/or the  MPI  executable  name.   Similarly,  all
                 arguments  after  the MPI executable name will be transparently passed as command line argument
                 to the MPI process and will be will be effectively ignored by mpirun.

DESCRIPTION

       mpiexec is loosely defined  in  the  Miscellany  chapter  of  the  MPI-2  standard  (see  http://www.mpi-
       forum.org/).   It  is  meant  to  be a portable mechanism for starting MPI processes.  The MPI-2 standard
       recommends several command line options, but does not mandate  any.   LAM's  mpiexec  currently  supports
       several of these options, but not all.

       LAM's  mpiexec  is  actually a perl script that is a wrapper around several underlying LAM commands, most
       notably lamboot, mpirun, and lamhalt.  As such, the functionality  provided  by  mpiexec  can  always  be
       performed manually.  Unless otherwise specified in arguments that are passed back to mpirun, mpiexec will
       use the per-CPU scheduling as described in mpirun(1) (i.e., the "cX" and "C" notation).

       mpiexec can either use an already-existing LAM  universe  (i.e.,  a  booted  LAM  run-time  environment),
       similar  to  mpirun,  or  can  be  used  for  "one-shot"  MPI  executions where it boots the LAM run-time
       environment, runs the MPI executable(s), and then shuts down the LAM run-time environment.

       mpiexec can also be used to launch MPMD MPI jobs from the command line.  mpirun also  supports  launching
       MPMD MPI jobs, but the user must make a text file appschema(5) first.

       Perhaps one of mpiexec's most useful features is the command-line ability to launch different executables
       on different architectures using the -arch flag (see EXAMPLES, below).  Essentially, the string  argument
       that  is  given to -arch is used as a pattern match against the output of the GNU config.guess utility on
       each node.  If the user-provided architecture string matches any subset of the output of config.guess, it
       is  ruled  a  match.   Wildcards are not possible.  The GNU config.guess utility is available both in the
       LAM/MPI     source     code     distribution     (in     the     config     subdirectory)     and      at
       ftp://ftp.gnu.org/gnu/config/config.guess.

       Some sample outputs from config.guess include:

       sparc-sun-solaris2.8
                 Solaris 2.8 running on a SPARC platform.

       i686-pc-linux-gnu
                 Linux running on an i686 architecture.

       mips-sgi-irix6.5
                 IRIX 6.5 running on an SGI/MIPS architecture.

       You  might  want  to  run the laminfo command on your available platforms to see what string config.guess
       reported.  See laminfo(1) for more details (e.g., the -arch flag to laminfo).

   Configfile option
       It is possible to specify any set of local parameters in a configuration file rather than on the  command
       line using the -configfile option.  This option is typically used when the number of command line options
       is too large for some shells, or when automated processes generate the command line arguments and  it  is
       simply more convenient to put them in a file for later processing by mpiexec.

       The  config file can contain both comments and one or more sets of local arguments.  Lines beginning with
       "#" are considered comments and are ignored.  Other lines are considered to be  one  or  more  groups  of
       local arguments.  Each group must be separated by either a newline or a colon (":").  For example:

         # Sample mpiexec config file
         # Launch foo on two nodes
         -host node1.example.com foo : -host node2.example.com foo
         # Launch two copies of bar on a third node
         -host node3.example.com -np 2 bar

ERRORS

       In the event of an error, mpiexec will do its best to shut everything down and return to the state before
       it was executed.  For example, if mpiexec was used to boot a LAM run-time environment,  mpiexec  will  do
       its  best  to  take  down  whatever  successfully booted of the run-time environment (to include invoking
       lamhalt and/or lamwipe).

EXAMPLES

       The following are some examples of how to use mpiexec.  Note  that  all  examples  assume  the  CPU-based
       scheduling (which does NOT map to physical CPUs) as described in mpirun(1).

       mpiexec -n 4 my_mpi_program
                 Launch 4 copies of my_mpi_program in an already-existing LAM universe.

       mpiexec -n 4 my_mpi_program arg1 arg2
                 Similar  to  the previous example, but pass "arg1" and "arg2" as command line arguments to each
                 copy of my_mpi_program.

       mpiexec -ssi rpi gm -n 4 my_mpi_program
                 Similar to the previous example, but pass "-ssi  rpi  gm"  back  to  mpirun  to  tell  the  MPI
                 processes to use the Myrinet (gm) RPI for MPI message passing.

       mpiexec -n 4 program1 : -n 4 program2
                 Launch  4 copies of program1 and 4 copies of program2 in an already-existing LAM universe.  All
                 8 resulting processes will share a common MPI_COMM_WORLD.

       mpiexec -machinefile hostfile -n 4 my_mpi_program
                 Boot the LAM run-time environment with the nodes listed  in  the  hostfile,  run  4  copies  of
                 my_mpi_program in the resulting LAM universe, and then shut down the LAM universe.

       mpiexec -machinefile hostfile my_mpi_program
                 Similar to above, but run my_mpi_program on all available CPUs in the LAM universe.

       mpiexec -arch solaris2.8 sol_program : -arch linux linux_program
                 Run  as  many  copies  of  sol_program as there are CPUs on Solaris machines in the current LAM
                 universe, and as many copies of linux_program as there  are  CPUs  on  linux  machines  in  the
                 current LAM universe.  All resulting processes will share a common MPI_COMM_WORLD.

       mpiexec -arch solaris2.8 sol2.8_prog : -arch solaris2.9 sol2.9_program
                 Similar  to  the  above example, except distinguish between Solaris 2.8 and 2.9 (since they may
                 have different shared libraries, etc.).

SEE ALSO

       appschema(5), bhost(5), lamboot(1), lamexec(1), mpirun(1)