MPIPreferences.jl

MPIPreferences.jl is a small package based on Preferences.jl for selecting MPI implementations. These choices are compile-time constants, and so any changes will require a Julia restart.

Consts

MPIPreferences.abiConstant
MPIPreferences.abi :: String

The ABI (application binary interface) of the currently selected binary. Supported values are:

  • "MPICH": MPICH-compatible ABI (https://www.mpich.org/abi/)
  • "OpenMPI": Open MPI compatible ABI (Open MPI, IBM Spectrum MPI, Fujitsu MPI)
  • "MicrosoftMPI": Microsoft MPI
  • "MPItrampoline": MPItrampoline
  • "HPE MPT": HPE MPT
source

Changing implementations

MPIPreferences.use_system_binaryFunction
use_system_binary(;
    library_names = ["libmpi", "libmpi_ibm", "msmpi", "libmpich", "libmpi_cray", "libmpitrampoline"],
    extra_paths = String[],
    mpiexec = "mpiexec",
    abi = nothing,
    vendor = nothing,
    export_prefs = false,
    force = true)

Switches the underlying MPI implementation to a system provided one. A restart of Julia is required for the changes to take effect.

Options:

  • library_names: a name or collection of names of the MPI library, passed to Libdl.find_library. If the library isn't in the library search path, you can specify the full path to the library.

  • extra_paths: indicate extra directories where to search for the MPI library, besides the default ones of the dynamic linker.

  • mpiexec: the MPI launcher executable. The default is mpiexec, but some clusters require using the scheduler launcher interface (e.g. srun on Slurm, aprun on PBS). It is also possible to pass a Cmd object to include specific command line options.

  • abi: the ABI of the MPI library. By default this is determined automatically using identify_abi. See abi for currently supported values.

  • vendor: can be either nothing or a vendor name (such a "cray"). If vendor has the value "cray", then the output from cc --cray-print-opts=all is parsed for which libraries are linked by the Cray Compiler Wrappers. Note that if mpi_gtl_* is present, then this .so will be added to the preloads. Also note that the inputs to library_names will be overwritten by the library name used by the compiler wrapper.

  • export_prefs: if true, the preferences into the Project.toml instead of LocalPreferences.toml.

  • force: if true, the preferences are set even if they are already set.

source
MPIPreferences.use_jll_binaryFunction
use_jll_binary([binary]; export_prefs=false, force=true)

Switches the underlying MPI implementation to one provided by JLL packages. A restart of Julia is required for the changes to take effect.

Available options are:

  • "MicrosoftMPI_jll" (Only option and default on Windows)
  • "MPICH_jll" (Default on all other platform)
  • "OpenMPI_jll"
  • "MPItrampoline_jll"

The export_prefs option determines whether the preferences being set should be stored within LocalPreferences.toml or Project.toml.

source

Utils

MPIPreferences.check_unchangedFunction
MPIPreferences.check_unchanged()

Throws an error if the preferences have been modified in the current Julia session, or if they are modified after this function is called.

This is should be called from the __init__() function of any package which relies on the values of MPIPreferences.

source

Preferences schema

MPIPreferences utilizes the following keys to store information in the Preferences key-value store.

  • _format: the version number of the schema. Currently only "1.0" is supported.
  • binary: the choice of binary. This should be one of the strings listed in MPIPreferences.binary.

If binary == "system", then the following keys are also required (otherwise they have no effect):

  • libmpi: the filename or path of the MPI dynamic library.
  • abi: The ABI of the MPI implementation. This should be one of the strings listed in MPIPreferences.abi.
  • mpiexec: either
    • a string corresponding to the MPI launcher executable
    • an array of strings, with the first entry being the executable and remaining entries being additional flags that should be used with the executable.