My new favorite Open MPI mpirun feature: tab completion

Today’s guest author is Nathan Hjelm, a Scientist 2 at Los Alamos National Laboratory.

We recently added scripts to support tab completion of mpirun flags and run-time MCA configuration variables to the Open MPI trunk development. The scripts support both bash and zsh and have a number of useful features (depending on the shell).

Can’t remember how to spell that MCA parameter name? Just hit <TAB>.
Can’t remember which transports are available? Just hit <TAB>.
Can’t remember the name of that mpirun CLI option? Just hit <TAB>.

Both the bash and zsh scripts support:

• Basic completion of all mpirun switches.
• Completion of MCA variable names for the -mca and -gmca switches.
• Completion of component names for selection variables (ex. -mca btl).
• Completion of variable values for enumerated variables.
• Completion of unique variable and component names. Names already specified on the command line are not completed again on the same command line.
• Display help messages as descriptions for MCA variable completions.

Additionally, the zsh script has support for:

• Enhanced completion of mpirun switches, including disabling completion of incompatible/duplicate switches, and descriptions of all switches.

And the bash script has additional support for:

• “Fuzzy” completion of MCA variable names and values.

Let me give an example of what these scripts do, and why they’re so useful. Remember that Open MPI currently has over 500 MCA variables; it is painfun to keep referring to the output of ompi_info and the mpirun command line to lookup variable names. Shell tab completion makes it much easier. Just hit tab to see what variables or components are currently available.

Completion of MCA variable names shows both matching names, and, if available, the help string associated with those names (I trimmed the full parameters descriptions because the blog CSS style doesn’t wrap words correctly; but know that the tab completion shows the full descriptions as relevant):

shell$ mpirun -mca btl_ugni_rdma_<TAB>
btl_ugni_rdma_pipeline_frag_size -- Maximum size (in bytes) of a single ...
btl_ugni_rdma_pipeline_send_length -- Length of the "phase 2" portion ...
btl_ugni_rdma_max_retries

 

For MCA parameters with well-defined values (e.g., plugin selection), you can use tab completion to see what values are available:

shell$ mpirun -mca btl self,<TAB>
sm ugni vader

 

Installing either of the shell completion scripts is very straightforward.

For bash, if bash completion is not already installed, follow the instructions here.

Then install mpirun completion by dropping contrib/completion/bash.sh into either the system bash_completion.d (usually found in /etc) or somewhere in your home directory (I use ~/.bash_completion.d).  If installing the script in a location other than the system-wide location, you need to add the following to either ~/.bash_profile or ~/.bash_completion:

[ -r /path/to/mpirun.sh ] && . /path/to/mpirun.sh

 

For zsh, if completion is not already set up, follow the instructions in section 20.2 of the zsh completion documentation.

Then copy contrib/completion/mpirun.zsh to _mpirun into any directory in your $fpath.  If needed, add another directory to $fpath (I use ~/.zsh/completion) by adding the following line to ~/.zshrc before the call to compinit:

fpath=(/path/to/completion/scripts $fpath)

 

Both script are currently in the development trunk and will be released as part of the Open MPI 1.7.4 release.