Run MPI On Grid'5000

From Grid5000
Jump to navigation Jump to search
Note.png Note

This page is actively maintained by the Grid'5000 team. If you encounter problems, please report them (see the Support page). Additionally, as it is a wiki page, you are free to make minor corrections yourself if needed. If you would like to suggest a more fundamental change, please contact the Grid'5000 team.


MPI is a programming interface that enables the communication between processes of a distributed memory system. This tutorial focuses on setting up MPI environments on Grid'5000 and only requires a basic understanding of MPI concepts. For instance, you should know that standard MPI processes live in their own memory space and communicate with other processes by calling library routines to send and receive messages. For a comprehensive tutorials on MPI, see the IDRIS course on MPI. There are several freely-available implementations of MPI, including Open MPI, MPICH2, MPICH, LAM, etc. In this practical session, we focus on the Open MPI implementation.

Before following this tutorial you should already have some basic knowledge of OAR (see the Getting Started tutorial) . For the second part of this tutorial, you should also know the basics about OARGRID (see the Advanced OAR tutorial).

Running MPI on Grid'5000

When attempting to run MPI on Grid'5000 you will face a number of challenges, ranging from classical setup problems for MPI software to problems specific to Grid'5000. This practical session aims at driving you through the most common use cases, which are:

  • Setting up and starting Open MPI on a default environment.
  • Setting up and starting Open MPI to use high performance interconnect.
  • Setting up and starting latest Open MPI library version.
  • Setting up and starting Open MPI to run on several sites using oargridsub.

Using Open MPI on a default environment

The default Grid'5000 environment provides Open MPI 4.1.0 (see ompi_info).

Creating a sample MPI program

For the purposes of this tutorial, we create a simple MPI program where the MPI process of rank 0 broadcasts an integer (42) to all the other processes. Then, each process prints its rank, the total number of processes and the value he received from the process 0.

In your home directory, create a file ~/mpi/tp.c and copy the source code:

Terminal.png frontend:
mkdir ~/mpi
Terminal.png frontend:
vi ~/mpi/tp.c
#include <stdio.h>
#include <mpi.h>
#include <time.h> /* for the work function only */
#include <unistd.h>

int main (int argc, char *argv []) {
       char hostname[257];
       int size, rank;
       int bcast_value = 1;

       gethostname(hostname, sizeof hostname);
       MPI_Init(&argc, &argv);
       MPI_Comm_rank(MPI_COMM_WORLD, &rank);
       MPI_Comm_size(MPI_COMM_WORLD, &size);
       if (!rank) {
            bcast_value = 42;
       MPI_Bcast(&bcast_value,1 ,MPI_INT, 0, MPI_COMM_WORLD );
       printf("%s\t- %d - %d - %d\n", hostname, rank, size, bcast_value);

       return 0;

You can then compile your code:

Terminal.png frontend:
mpicc ~/mpi/tp.c -o ~/mpi/tp

Setting up and starting Open MPI on a default environment

Submit a job:

Terminal.png frontend:
oarsub -I -l nodes=3

OAR provides the $OAR_NODEFILE file, containing the list of nodes of the job (one line per CPU core). You can use it to launch your parallel job:

Terminal.png node:
mpirun -machinefile $OAR_NODEFILE ~/mpi/tp

You should have something like:

helios-52       - 4 - 12 - 42
helios-51       - 0 - 12 - 42
helios-52       - 5 - 12 - 42
helios-51       - 2 - 12 - 42
helios-52       - 6 - 12 - 42
helios-51       - 1 - 12 - 42
helios-51       - 3 - 12 - 42
helios-52       - 7 - 12 - 42
helios-53       - 8 - 12 - 42
helios-53       - 9 - 12 - 42
helios-53       - 10 - 12 - 42
helios-53       - 11 - 12 - 42

You may have (lot's of) warning messages if Open MPI cannot take advantage of any high performance hardware. At this point of the tutorial, this is not important as we will learn how to select clusters with high performance interconnect in greater details below. Error messages might look like this:

[1637577186.512697] [taurus-10:2765 :0]      rdmacm_cm.c:638  UCX  ERROR rdma_create_event_channel failed: No such device
[1637577186.512752] [taurus-10:2765 :0]     ucp_worker.c:1432 UCX  ERROR failed to open CM on component rdmacm with status Input/output error
[] ../../../../../../ompi/mca/pml/ucx/pml_ucx.c:273  Error: Failed to create UCP worker

To tell OpenMPI not try to use high performance hardware and avoid those warnings message, use the following options:

Terminal.png node:
mpirun --mca pml ^ucx -machinefile $OAR_NODEFILE $HOME/mpi_programm
Note.png Note

In case you submitted a job that does not reserve entire nodes (all CPU cores of all nodes), you have to use oarsh as MPI remote shell connector. To do so with Open MPI, you can add --mca orte_rsh_agent "oarsh" to your mpirun command line. Open MPI will then use oarsh in place of ssh.

Terminal.png node:
mpirun --mca orte_rsh_agent "oarsh" -machinefile $OAR_NODEFILE ~/mpi/tp

You can also set an environment variable (usually in your .bashrc):

Terminal.png bashrc:
export OMPI_MCA_orte_rsh_agent=oarsh
Terminal.png node:
mpirun -machinefile $OAR_NODEFILE ~/mpi/tp

Open MPI also provides a configuration file for --mca parameters. In your home directory, create a file as ~/.openmpi/mca-params.conf


Setting up and starting Open MPI to use high performance interconnect

Open MPI provides several alternative compononents to use High Performance Interconnect hardware (such as Infiniband or Omni-Path).

MCA parameters (--mca) can be used to select the component that are used at run-time by OpenMPI. To learn more about the MCA parameters, see also:

Open MPI packaged in Grid'5000 debian11 includes ucx, ofi and openib components to make use of Infiniband network, and psm2 and ofi to make use of Omnipath network.

If you want some of these components, you can for example use --mca pml ^ucx --mca mtl ^psm2,ofi --mca btl ^ofi,openib. This disables all high performance components mentionned above and will force Open MPI to use its TCP backend.

Infiniband network

By default, OpenMPI tries to use Infiniband high performance interconnect using the UCX component. When Infiniband network is available, it will provide best results in most of cases (UCX even uses multiple interfaces at a time when available).

Omni-Path network

For Open MPI to work with Omni-Path network hardware, PSM2 component must be used. It is recommended to explicitly disable other components (otherwise, OpenMPI will try to load other components which may produce error messages or provide lower performance):

Terminal.png node:
mpirun -machinefile $OAR_NODEFILE -mca mtl psm2 -mca pml ^ucx,ofi -mca btl ^ofi,openib ~/mpi/tp

IP over Infiniband or Omni-Path

Nodes with Infiniband or Omni-Path network interfaces also provide an IP over Infiniband interface (these interfaces are named ibX). The TCP backend of Open MPI will try to use them by default.

You can explicitely select interfaces used by the TCP backend using for instance --mca btl_tcp_if_exclude ib0,lo (to avoid using IP over Infiniband and local interfaces) or --mca btl_tcp_if_include eno2 (to force using the 'regular' Ethernet interface eno2).


We will be using OSU micro benchmark to check the performances of high performance interconnects.

To download, extract and compile our benchmark, do:

Terminal.png frontend:
cd ~/mpi
Terminal.png frontend:
tar xf osu-micro-benchmarks-5.8.tgz
Terminal.png frontend:
cd osu-micro-benchmarks-5.8/
Terminal.png frontend:
./configure CC=$(which mpicc) CXX=$(which mpicxx)
Terminal.png frontend:

As we will benchmark two MPI processes, reserve only one core in two distinct nodes.

Terminal.png frontend:
oarsub -I -l nodes=2

To start the network benchmark, use:

Terminal.png node:
mpirunmpirun -machinefile $OAR_NODEFILE -npernode 1 ~/mpi/osu-micro-benchmarks-5.8/mpi/pt2pt/osu_latency

The option `-npernode 1` tells to only spawn one process on each node, as the benchmark requires only two processes to communicate.

You can then try to compare performance of various network hardware available on Grid'5000. See for instance Network section of Hardware page.

OAR can select nodes according to properties related to network performance. For example:

  • To reserve one core of two distinct nodes with a 56Gbps InfiniBand interconnect:
Terminal.png frontend:
oarsub -I -l /nodes=2/core=1 -p "ib_rate=56"
  • To reserve one core of two distinct nodes with a 100Gbps Omni-Path interconnect:
Terminal.png frontend:
oarsub -I -l /nodes=2/core=1 -p "opa_rate=100"

Use a newer Open MPI version using modules

Newer Open MPI versions are available as module. To list available versions, use this command.

Terminal.png frontend:
module av openmpi/

This will load chosen Open MPI to execution your environment:

Terminal.png frontend:
module load openmpi/4.1.4_gcc-10.4.0
Terminal.png frontend:
mpirun --version

You must recompile simple MPI example on the frontend with this new version.

Terminal.png frontend:
mpicc ~/mpi/tp.c -o ~/mpi/tp

From your job, you must ensure the same Open MPI version is used on every nodes:

Terminal.png frontend:
oarsub -I -l nodes=3
Terminal.png node:
module load openmpi/4.1.4_gcc-10.4.0
Terminal.png node:
$(which mpirun) -machinefile $OAR_NODEFILE ~/mpi/tp

Note that $(which mpirun) command is used in this last step to ensure mpirun from the module environment is used.

Installing Open MPI in a conda environment

Here's an example of installing Open MPI in a conda environment optimized with ucx to use the cluster's high-bandwidth and low-latency.

We work on Grenoble site

UCX exposes a set of abstract communication primitives that utilize the best of available hardware resources and offloads. These include RDMA (InfiniBand and RoCE), TCP, GPUs, shared memory, and network atomic operations.

  • Install OpenMPI, ucx, and GCC from conda-forge channel
Terminal.png fgrenoble:
conda install -c conda-forge gcc_linux-64 openmpi ucx

Note: do not forget to create a dedicated environment before.

Test installation via NetPIPE
  • Install NetPIPE to test latency and network throughput (NetPIPE not available as conda package)
Terminal.png fgrenoble:
cd $HOME ; mkdir SRC && cd SRC
Terminal.png fgrenoble:
tar zvxf NetPIPE-3.7.2.tar.gz
Terminal.png fgrenoble:
cd NetPIPE-3.7.2/ && make mpi
  • Reserve 2 cores on 2 separate nodes and enter into interactive session (ex: cluster dahu in Grenoble) :
Terminal.png fgrenoble:
oarsub -I -p dahu -l /nodes=2/core=1

Note: choose an appropriate cluster with OminPath or InfiniBand Network connection to compare performance between two nodes using or not ucx driver. See Grid'5000 Hardware Documentation.

  • On node dahu-X : Load conda, activate your conda environment, modify $PATH
Terminal.png dahu:
module load miniconda3 && eval "$(conda shell.bash hook)"
Terminal.png dahu:
conda activate <env_name>
Terminal.png dahu:
export PATH=~/SRC/NetPIPE-3.7.2:$PATH
  • Run MPI without ucx (use standard network):
Terminal.png dahu:
mpirun -np 2 --machinefile $OAR_NODEFILE --prefix $CONDA_PREFIX --mca plm_rsh_agent oarsh NPmpi
0: dahu-3
1: dahu-30
Now starting the main loop
  0:       1 bytes   6400 times -->      0.54 Mbps in      14.21 usec
  1:       2 bytes   7035 times -->      1.07 Mbps in      14.20 usec
  2:       3 bytes   7043 times -->      1.61 Mbps in      14.22 usec
116: 4194304 bytes     12 times -->   8207.76 Mbps in    3898.75 usec
117: 4194307 bytes     12 times -->   8161.45 Mbps in    3920.87 usec
  • Run MPI with ucx (use rapid network):
Terminal.png dahu:
mpirun -np 2 --machinefile $OAR_NODEFILE --prefix $CONDA_PREFIX --mca plm_rsh_agent oarsh --mca pml ucx --mca osc ucx NPmpi
0: dahu-3
1: dahu-30
Now starting the main loop
  0:       1 bytes  19082 times -->      1.69 Mbps in       4.50 usec
  1:       2 bytes  22201 times -->      3.08 Mbps in       4.95 usec
  2:       3 bytes  20212 times -->      4.46 Mbps in       5.13 usec
116: 4194304 bytes     46 times -->  30015.10 Mbps in    1066.13 usec
117: 4194307 bytes     46 times -->  30023.66 Mbps in    1065.83 usec

More advanced use cases

Running MPI on several sites at once

In this section, we are going to execute a MPI process over several Grid'5000 sites. In this example we will use the following sites: Rennes, Sophia and Grenoble, using oargrid for making the reservation (see the Advanced OAR tutorial for more information).

Warning.png Warning

Open MPI tries to figure out the best network interface to use at run time. However, selected networks are not always "production" Grid'5000 network which is routed between sites. In addition, only TCP implementation will work between sites, as high performance networks are only available from the inside of a site. To ensure correct network is selected, add the option --mca opal_net_private_ipv4 "" --mca btl_tcp_if_exclude ib0,lo --mca btl self,cm,tcp --mca pml ^ucx,cm to mpirun

Warning.png Warning

By default, Open MPI may use only the short name of the nodes specified into the nodesfile; but to join grid5000 nodes that are located on different sites, we must use the FQDN names. For Open Mpi to correctly use FQDN names of the nodes, you must add the following option to mpirun: --mca orte_keep_fqdn_hostnames t

The MPI program must be available on each site you want to use. From the frontend of one site, copy the mpi/ directory to the two other sites. You can do that with rsync. Suppose that you are connected in Sophia and that you want to copy Sophia's mpi/ directoy to Grenoble and Rennes.

Terminal.png fsophia:
rsync -avz ~/mpi/
Terminal.png fsophia:
rsync -avz ~/mpi/

(you can also add the --delete option to remove extraneous files from the mpi directory of Nancy and Grenoble).

Reserve nodes in each site from any frontend with oargridsub (you can also add options to reserve nodes from specific clusters if you want to):

Terminal.png frontend:
oargridsub -w 02:00:00 nancy:rdef="nodes=2",grenoble:rdef="nodes=2",sophia:rdef="nodes=2" > oargrid.out

Get the node list using oargridstat and copy the list to the first node:

Terminal.png frontend:
oargridstat -w -l $OARGRID_JOB_ID | grep -v ^$ > ~/gridnodes
Terminal.png frontend:
scp ~/gridnodes $(head -1 ~/gridnodes):

Connect to the first node:

Terminal.png frontend:
ssh $(head -1 ~/gridnodes)

And run your MPI application:

Terminal.png node:
cd ~/mpi/
Terminal.png node:
mpirun -machinefile ~/gridnodes --mca opal_net_private_ipv4 "" --mca btl_tcp_if_exclude ib0,lo --mca btl self,vader,tcp --mca pml ^ucx,cm --mca orte_keep_fqdn_hostnames t tp

MPI and GPU to GPU communications

Direct GPU to GPU exchange of data (without having to transit on system RAM) is available with OpenMPI. On Grid'5000, this feature is currently only supported for AMD GPUs on the same node (see bug #13559 and bug #13540 for progress on other use cases).

This feature is available using the module version of OpenMPI. Will use OSU benchmark to demonstrate GPU to GPU communiction:

module load hip
module load openmpi

tar xf osu-micro-benchmarks-5.9.tar.gz
cd osu-micro-benchmarks-5.9/

./configure --enable-rocm --with-rocm=$(hipconfig -p) CC=mpicc CXX=mpicxx LDFLAGS="-L$(ompi_info | grep Prefix: | cut -d': ' -f2)/lib/ -lmpi -L$(hipconfig -p)/lib/ $(hipconfig -C) -lamdhip64" CPPFLAGS="-std=c++11"

Then run OSU benchmark:

mpirun -np 2 --mca pml ucx -x UCX_TLS=self,sm,rocm mpi/pt2pt/osu_bw -d rocm D D

The benchmark will report GPU to GPU bandwidth.

See also


Passing environment variables to nodes

While some batch schedulers (e.g. Slurm) transparently pass environment variables from the head node shell to all execution nodes given to mpirun. OAR does not (OAR provides no more than what OpenSSH does, be it when using oarsh or ssh as the connector). Thus OAR leaves this responsibility of environment variables passing to mpirun.

Therefore, in order to have more than the default environment variables (OMPI_* variables) passed/set on execution nodes, one has different options:

use the -x VAR option of mpirun, possibly for each variable to pass (WARNING, -x is depreacted)
mpirun -machinefile $OAR_NODE_FILE -x MY_ENV1 -x MY_ENV2 -x MY_ENV3="value3" ~/bin/mpi_test
use the --mca mca_base_env_list "ENV[;...]" option of mpirun
mpirun -machinefile $OAR_NODE_FILE --mca mca_base_env_list "MY_ENV1;MY_ENV2;MY_ENV3=value3" ~/bin/mpi_test
set the mca_base_env_list "ENV[;...]" option in the ~/.openmpi/mca-params.conf file
This way passing variable become transparent to the mpirun command line, which becomes:
mpirun -machinefile $OAR_NODE_FILE ~/bin/mpi_test
-x and --mca mca_base_env_list cannot coexist.

This could especially be useful to pass OpenMP variables, such as OMP_NUM_THREADS.

More info in OpenMPI manual pages.