init - Initialize the tool#

This command initializes the E4S Container Launcher by generating a template profile from the environment.

Usage#

e4s-cl init [--mpi <path>] \
    [--launcher <string>] \
    [--launcher_args <string>] \
    [ OPTIONS ] [ [ LAUNCHER [ -- ] ] COMMAND ]

or

e4s-cl init --system <string> [OPTIONS]

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.

Common options#

These arguments’ values will be directly added to the created profile.

--profile: Name of the profile to create or overwrite
--backend: Container technology to employ
--image: Identifier for the image to use when launching the container
--source: Script to run before execution
--wi4mpi: Path to a Wi4MPI installation to use

MPI analysis options#

These arguments influence the analysis. They cannot be used with --system

--mpi: Path to a MPI installation to use instead of the system default
--launcher: Process launcher executable to use. Default is mpirun.
--launcher_args: Arguments to use with the process launcher.

System option#

This argument allows to select a pre-made profile.

--system: System name, will use a matching builtin profile if available

Description#

This command is intended to be run once, and will create a profile from the resources made available to it. Initialization can be achieved in multiple ways, depending on the arguments passed to the command.

In case no method is explicitly invoked, the command attempts MPI library analysis, by using the MPI compiler and launcher available in the environment.

Using an installed MPI library#

This initialization method will create a profile from the execution analysis of a sample MPI program. A program compiled with the MPI library’s compiler will run in a debug environment. The opened files and libraries will be detected using the ptrace system call, and added to the resulting profile.

The sample command used depends on the arguments given to e4s-cl. An entire command can be passed on the command line, or it will be constructed from the --mpi, --launcher and --launcher_args options.

It is highly encouraged to load the MPI library beforehand using the module system available (spack/modules/lmod) to ensure the paths and dependencies are valid and loaded.

The importance of inter-process communication

This process relies on the execution of a sample MPI program to discover its dependencies. In some cases, a library will lazy-load network libraries, preventing them from being detected. A message will appear in case some limitations were detected.

If no name is passed to --profile, a profile name will be generated from the version of the found MPI library.

Using a system name#

If the current system is supported, use the --system argument to flag its use. The available values are listed when using e4s-cl init -h. In order to have the system-specific profiles available (and listed as available), the E4SCL_TARGETSYSTEM=<system> flag needs to be used when installing the project.

Examples#

Initializing using MPI resources from the environment:

module load mpich
e4s-cl init

Initializing by passing a MPI command:

module load mpich
e4s-cl init mpirun -np 2 ./sample-program

Using a library installed on the system in /packages:

e4s-cl init --mpi /packages/mpich --profile mpich