MPIEXEC(1)

✨ MPIEXEC(1) — LAM COMMANDS ✨

okay bestie, welcome to the LAM COMMANDS manual, this is the mpiexec page and it's literally the moment you've been waiting for 💅

---

🎀 NAME 🎀

mpiexec — run MPI programs on LAM nodes. that's it, that's the vibe 🦋

---

🌸 SYNOPSIS 🌸

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

mpiexec [global_args] -configfile filename

---

✨ OPTIONS ✨

so global arguments are the ones that apply to all the commands mpiexec is gonna launch. they go at the very beginning of the command line, no cap 👑

• -boot — boot the LAM run-time environment before running the MPI program. if -machinefile isn't specified, it uses the default boot schema. and when the MPI processes finish, the LAM run-time environment gets shut down. it's giving one-shot energy 🔥
• -boot-args args — pass args to the back-end lamboot command when booting the LAM run-time environment. implies -boot.
• -d — enable lots of debugging output. implies -v. it's a lot, bestie, prepare yourself 😭
• -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, 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, so check your version first fr fr.
• -ssi key value — set the SSI parameter key to the value value.
• -tv — launch the MPI processes under the TotalView debugger 🐛
• -v — be verbose. say more words, we love that ✨

one or more sets of local arguments must be specified (or a config file; see below). local arguments basically include everything allowed in an appschema(5), plus these options from the MPI-2 standard — and heads up: the options listed below have to 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 basically uses the architecture you give it 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 it doesn't recognize (like an appschema(5) argument, or the MPI executable name), the rest of the arguments get passed back to mpirun to actually start the process. so like, all of mpiexec's arguments described above must come before appschema arguments and/or the MPI executable name. same energy on the other side: all arguments after the MPI executable name get transparently passed as command line arguments to the MPI process, and are effectively ignored by mpirun. the way that it just hands them off 🫶

---

💖 DESCRIPTION 💖

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

LAM's mpiexec is actually a perl script that's a wrapper around several underlying LAM commands, most notably lamboot, mpirun, and lamhalt. so the functionality it gives you can always be done manually, iykyk. unless otherwise specified in arguments that get passed back to mpirun, mpiexec will use the per-CPU scheduling 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 it can be used for "one-shot" MPI executions where it boots the LAM run-time environment, runs the MPI executable(s), and then shuts the LAM run-time environment down. ✨

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

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 you give to -arch is used as a pattern match against the output of the GNU config.guess utility on each node. if the architecture string you provided matches any subset of the output of config.guess, it's ruled a match. wildcards are not possible — not even a little. 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 wanna 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's totally possible to specify any set of local parameters in a configuration file instead of on the command line, using the -configfile option. this 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's just more convenient to put them in a file for later processing by mpiexec. so organized 🎀

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. it's giving cleanup crew 🧹

---

🔥 EXAMPLES 🔥

here 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). important, bestie 📌

• 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. sharing is caring 🫶
• 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, 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 it distinguishes 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)

---

and that's the whole page bestie, you ate that 💅 this was LAM 7.1.4, dated July, 2007 — iconic, timeless, periodt. go launch something 🦋✨💖