The instructions on this page show how to build and run a simple MPI program using an E4S base container available from DockerHub.

Step 1: Docker Image

Download E4S base image ecpe4s/ubuntu20.04

This Ubuntu 20.04 image has Spack, MPI, and a few other package pre-installed, useful for quick start

Step 2: MPI Code

Produce an MPI example code, your code or the example below

The code below performs a simple ping-pong test on two MPI processes, or you can provide your own example code

Step 3: Run container

Run the container in interactive mode, obtaining a command prompt

Interactive mode provides you with command line access to an E4S-enabled Linux machine

Step 4: Compile and run code

Load MPI using Spack, compile your code and run it!

The E4S container has Spack and MPI pre-installed, all other E4S products readily available

Getting Started with MPI Using the E4S Base Container

(Docker Desktop on macOS or Linux)

This short guide walks you through four simple conceptual steps to run an MPI program inside an E4S container using the ecpe4s/ubuntu20.04 base image.
The process is portable, reproducible, and works on any system running Docker Desktop.

1. Download the E4S Base Image

Pull the E4S base container:

docker pull ecpe4s/ubuntu20.04:latest

Verify the image exists locally:

docker images ecpe4s/ubuntu20.04

2. Create a Simple MPI Example

Create a working directory:

mkdir ~/mpi-test
cd ~/mpi-test

Create an MPI source file named pingpong.c:

#include <mpi.h>
#include <stdio.h>

int main(int argc, char **argv) {
    int rank, tag = 0;
    char msg = 'x';
    MPI_Status status;

    MPI_Init(&argc, &argv);
    MPI_Comm_rank(MPI_COMM_WORLD, &rank);

    for (int i = 0; i < 10; i++) {
        if (rank == 0) {
            MPI_Send(&msg, 1, MPI_CHAR, 1, tag, MPI_COMM_COMM_WORLD);
            MPI_Recv(&msg, 1, MPI_CHAR, 1, tag, MPI_COMM_WORLD, &status);
            printf("Iteration %d: Rank 0 received pong\n", i);
        } else if (rank == 1) {
            MPI_Recv(&msg, 1, MPI_CHAR, 0, tag, MPI_COMM_WORLD, &status);
            MPI_Send(&msg, 1, MPI_CHAR, 0, tag, MPI_COMM_WORLD);
            printf("Iteration %d: Rank 1 sent pong\n", i);
        }
    }

    MPI_Finalize();
    return 0;
}

3. Run the Container in Interactive Mode

Use Docker Desktop to start an interactive shell inside the E4S container:

docker run -it --rm \
    -v $PWD:/work \
    -w /work \
    ecpe4s/ubuntu20.04:latest /bin/bash

Verify your source file is visible:

ls

Expected output:

pingpong.c

4. Load MPI Using Spack, Compile, and Run!

Inside the container:

Load an MPI implementation:

spack load mpich

Verify the MPI compiler is available:

mpicc --version

Compile your MPI program:

mpicc -O2 -o pingpong pingpong.c

Run the MPI application:

mpirun -n 2 ./pingpong

You should see output showing message exchange between rank 0 and rank 1.

🎉 Congratulations!

You now have a complete MPI workflow running inside an E4S container:

  • E4S base image downloaded
  • MPI program created
  • Interactive container session started
  • MPI loaded via Spack, compiled, and executed