Skip to content

use-quick-start.md

Latest commit

 

History

History
176 lines (124 loc) · 4.01 KB

use-quick-start.md

File metadata and controls

176 lines (124 loc) · 4.01 KB
layout single
title E4S Quick Start
permalink /quick-start/
classes wide
sidebar
nav
usemenu

{% include e4s-page-actions.html %}

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

{% include e4s-card-style.html %}

{% include e4s-two-card-content.html card1_title="Step 1: Docker Image" card1_front_text="Download E4S base image ecpe4s/e4s-spack-cpu" card1_back_text="This Ubuntu image has Spack, MPI, and a few other packages pre-installed, useful for a quick start." card2_title="Step 2: MPI Code" card2_front_text="Produce an MPI example code, your code or the example below." card2_back_text="The code below performs a simple ping-pong test on two MPI processes, or you can provide your own example code." %}

{% include e4s-two-card-content.html card1_title="Step 3: Run container" card1_front_text="Run the container in interactive mode, obtaining a command prompt." card1_back_text="Interactive mode provides you with command line access to an E4S-enabled Linux machine." card2_title="Step 4: Compile and run code" card2_front_text="Load MPI using Spack, compile your code and run it!" card2_back_text="The E4S container has Spack and MPI pre-installed, with all other E4S products readily available." %}

{% include e4s-card-script.html %}

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/e4s-spack-cpu:latest

Verify the image exists locally:

docker images ecpe4s/e4s-spack-cpu

2. Create a Simple MPI Example

Create a working directory:

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

Some hosts may have security measures that interfere with writing to a mounted directory. If necessary, you can open the directory permissions as a workaround:

chmod 777 ~/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_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 \
  --entrypoint bash \
  -v "$PWD:/work" \
  -w /work \
  ecpe4s/e4s-spack-cpu

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