launch - Run MPI commands

Run a command in a container supplemented with select host libraries.

Usage

e4s-cl launch [ OPTIONS ] [ LAUNCHER [ -- ] ] < COMMAND >

Arguments

Positional arguments

LAUNCHER

An MPI launcher binary and arguments. e4s-cl is compatible with several launchers and will detect their presence. Optional.

COMMAND

The command to run in a container. Required.

MPI launcher detection

E4S Container Launcher needs to determine the exact arguments of the launcher. Certain launchers may have unique options that e4s-cl may not recognize.

To ensure the arguments are understood correctly, an additional -- can be added between the launcher options and the command.

See the examples below for an illustration.

Optional arguments

The launch command accepts several arguments to tune its execution:

--profile

Profile to use for the execution. If unspecified, the selected profile will be used.

--image

Image to use when launching the container. Can be a path or identifier. [needed]

--backend

Container technology to employ. [needed]

--libraries

Comma-separated list of libraries to make available at run-time in the container. Optional.

--files

Comma-separated list of files to make accessible in the container. They will be bound in-place in the container. Optional.

--source

Path of a script to source before execution. Optional.

--from

If MPI library translation is needed, specify which family the binary comes from. The following are implemented: intelmpi, openmpi, mpich. Optional. See MPI implementations for details.

-h, --help

print a help message

[needed] (1,2)

This information is required for execution, but can be set by the selected profile and the option can be omitted from the command line.

Description

The launch command is responsible for executing commands in containers with the requested MPI environment.

Running a command is done by prefixing a regular MPI launcher command with e4s-cl launch.

Using profiles

The preferred way of passing options is by using a selected profile or profile specified with the --profile option. This way, the contents of the given profile are implicitly used, bypassing the need to specify any of the options manually. However, options given on the command line options have precedence over profiles’ fields.

MPI translation

In case the MPI library used on the host and container do not belong to the same family, the --from option can be used to specify which MPI family the binary was compiled with. e4s-cl will then take measures to translate MPI calls from the binary’s MPI to the one passed as an argument. This is done using Wi4MPI.

Examples

A launch command using an explicit profile and an MPI launcher:

e4s-cl launch --profile intel-21 mpirun -np 2 ./ping-pong

A launch command using an explicit profile and an MPI launcher, but a different image than the profile’s:

e4s-cl launch --profile intel-21 \
    --image /home/user/ecp.simg \
        mpirun -np 2 ./ping-pong

A launch command with implicit profile making explicit the launcher and command:

e4s-cl launch mpirun -np 2 -ppn 1 -- ./ping-pong

A launch command importing binaries in the container before running a script without profile:

e4s-cl launch --files /bin/strace,/bin/lsof \
    --backend singularity \
    --image ~/Images/ecp.simg \
        ./script.sh

A launch command using a local mpich library without profile:

e4s-cl launch --backend singularity \
     --image /home/user/ecp.simg \
     --libraries /spack/opt/[...]/mpich-3.4.1-xyz/lib/libmpi.so.12 \
     --files /usr/share/hwdata/pci.ids \
         mpirun -np 2 ./ping-pong

A implicit launch command (parameters implicitly passed via selected profile):

e4s-cl mpirun -np 2 ./ping-pong