FindMPI¶
Find a Message Passing Interface (MPI) implementation.
The Message Passing Interface (MPI) is a library used to write high-performance distributed-memory parallel applications, and is typically deployed on a cluster. MPI is a standard interface (defined by the MPI forum) for which many implementations are available.
Added in version 3.10: Major overhaul of the module: many new variables, per-language components, support for a wider variety of runtimes.
Variables for using MPI¶
The module exposes the components C, CXX, MPICXX and Fortran.
Each of these controls the various MPI languages to search for.
The difference between CXX and MPICXX is that CXX refers to the
MPI C API being usable from C++, whereas MPICXX refers to the MPI-2 C++ API
that was removed again in MPI-3.
Depending on the enabled components the following variables will be set:
MPI_FOUNDVariable indicating that MPI settings for all requested languages have been found. If no components are specified, this is true if MPI settings for all enabled languages were detected. Note that the
MPICXXcomponent does not affect this variable.MPI_VERSIONMinimal version of MPI detected among the requested languages, or all enabled languages if no components were specified.
This module will set the following variables per language in your
project, where <lang> is one of C, CXX, or Fortran:
MPI_<lang>_FOUNDVariable indicating the MPI settings for
<lang>were found and that simple MPI test programs compile with the provided settings.MPI_<lang>_COMPILERMPI compiler for
<lang>if such a program exists.MPI_<lang>_COMPILE_OPTIONSCompilation options for MPI programs in
<lang>, given as a ;-list.MPI_<lang>_COMPILE_DEFINITIONSCompilation definitions for MPI programs in
<lang>, given as a ;-list.MPI_<lang>_INCLUDE_DIRSInclude path(s) for MPI header.
MPI_<lang>_LINK_FLAGSLinker flags for MPI programs.
MPI_<lang>_LIBRARIESAll libraries to link MPI programs against.
Added in version 3.9: Additionally, the following IMPORTED targets are defined:
MPI::MPI_<lang>Target for using MPI from
<lang>.
The following variables indicating which bindings are present will be defined:
MPI_MPICXX_FOUNDVariable indicating whether the MPI-2 C++ bindings are present (introduced in MPI-2, removed with MPI-3).
MPI_Fortran_HAVE_F77_HEADERTrue if the Fortran 77 header
mpif.his available.MPI_Fortran_HAVE_F90_MODULETrue if the Fortran 90 module
mpican be used for accessing MPI (MPI-2 and higher only).MPI_Fortran_HAVE_F08_MODULETrue if the Fortran 2008
mpi_f08is available to MPI programs (MPI-3 and higher only).
If possible, the MPI version will be determined by this module. The facilities to detect the MPI version were introduced with MPI-1.2, and therefore cannot be found for older MPI versions.
MPI_<lang>_VERSION_MAJORMajor version of MPI implemented for
<lang>by the MPI distribution.MPI_<lang>_VERSION_MINORMinor version of MPI implemented for
<lang>by the MPI distribution.MPI_<lang>_VERSIONMPI version implemented for
<lang>by the MPI distribution.
Note that there's no variable for the C bindings being accessible through mpi.h, since the MPI standards
always have required this binding to work in both C and C++ code.
For running MPI programs, the module sets the following variables
MPIEXEC_EXECUTABLEExecutable for running MPI programs, if such exists.
MPIEXEC_NUMPROC_FLAGFlag to pass to
mpiexecbefore giving it the number of processors to run on.MPIEXEC_MAX_NUMPROCSNumber of MPI processors to utilize. Defaults to the number of processors detected on the host system.
MPIEXEC_PREFLAGSFlags to pass to
mpiexecdirectly before the executable to run.MPIEXEC_POSTFLAGSFlags to pass to
mpiexecafter other flags.
Variables for locating MPI¶
This module performs a four step search for an MPI implementation:
Search for
MPIEXEC_EXECUTABLEand, if found, use its base directory.Check if the compiler has MPI support built-in. This is the case if the user passed a compiler wrapper as
CMAKE_<LANG>_COMPILERor if they use Cray system compiler wrappers.Attempt to find an MPI compiler wrapper and determine the compiler information from it.
Try to find an MPI implementation that does not ship such a wrapper by guessing settings. Currently, only Microsoft MPI and MPICH2 on Windows are supported.
For controlling the MPIEXEC_EXECUTABLE step, the following variables may be set:
MPIEXEC_EXECUTABLEManually specify the location of
mpiexec.MPI_HOMESpecify the base directory of the MPI installation.
ENV{MPI_HOME}Environment variable to specify the base directory of the MPI installation.
ENV{I_MPI_ROOT}Environment variable to specify the base directory of the MPI installation.
For controlling the compiler wrapper step, the following variables may be set:
MPI_<lang>_COMPILERSearch for the specified compiler wrapper and use it.
MPI_<lang>_COMPILER_FLAGSFlags to pass to the MPI compiler wrapper during interrogation. Some compiler wrappers support linking debug or tracing libraries if a specific flag is passed and this variable may be used to obtain them.
MPI_COMPILER_FLAGSUsed to initialize
MPI_<lang>_COMPILER_FLAGSif no language specific flag has been given. Empty by default.MPI_EXECUTABLE_SUFFIXA suffix which is appended to all names that are being looked for. For instance you may set this to
.mpichor.openmpito prefer the one or the other on Debian and its derivatives.
In order to control the guessing step, the following variable may be set:
MPI_GUESS_LIBRARY_NAMEValid values are
MSMPIandMPICH2. If set, only the given library will be searched for. By default,MSMPIwill be preferred overMPICH2if both are available. This also setsMPI_SKIP_COMPILER_WRAPPERtotrue, which may be overridden.
Each of the search steps may be skipped with the following control variables:
MPI_ASSUME_NO_BUILTIN_MPIIf true, the module assumes that the compiler itself does not provide an MPI implementation and skips to step 2.
MPI_SKIP_COMPILER_WRAPPERIf true, no compiler wrapper will be searched for.
MPI_SKIP_GUESSINGIf true, the guessing step will be skipped.
Additionally, the following control variable is available to change search behavior:
MPI_CXX_SKIP_MPICXXAdd some definitions that will disable the MPI-2 C++ bindings. Currently supported are MPICH, Open MPI, Platform MPI and derivatives thereof, for example MVAPICH or Intel MPI.
If the find procedure fails for a variable MPI_<lang>_WORKS, then the settings detected by or passed to
the module did not work and even a simple MPI test program failed to compile.
If all of these parameters were not sufficient to find the right MPI implementation, a user may
disable the entire autodetection process by specifying both a list of libraries in MPI_<lang>_LIBRARIES
and a list of include directories in MPI_<lang>_ADDITIONAL_INCLUDE_DIRS.
Any other variable may be set in addition to these two. The module will then validate the MPI settings and store the
settings in the cache.
Cache variables for MPI¶
The variable MPI_<lang>_INCLUDE_DIRS will be assembled from the following variables.
For C and CXX:
MPI_<lang>_HEADER_DIRLocation of the
mpi.hheader on disk.
For Fortran:
MPI_Fortran_F77_HEADER_DIRLocation of the Fortran 77 header
mpif.h, if it exists.MPI_Fortran_MODULE_DIRLocation of the
mpiormpi_f08modules, if available.
For all languages the following variables are additionally considered:
MPI_<lang>_ADDITIONAL_INCLUDE_DIRSA ;-list of paths needed in addition to the normal include directories.
MPI_<include_name>_INCLUDE_DIRPath variables for include folders referred to by
<include_name>.MPI_<lang>_ADDITIONAL_INCLUDE_VARSA ;-list of
<include_name>that will be added to the include locations of<lang>.
The variable MPI_<lang>_LIBRARIES will be assembled from the following variables:
MPI_<lib_name>_LIBRARYThe location of a library called
<lib_name>for use with MPI.MPI_<lang>_LIB_NAMESA ;-list of
<lib_name>that will be added to the include locations of<lang>.
Usage of mpiexec¶
When using MPIEXEC_EXECUTABLE to execute MPI applications, you should typically
use all of the MPIEXEC_EXECUTABLE flags as follows:
${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${MPIEXEC_MAX_NUMPROCS}
${MPIEXEC_PREFLAGS} EXECUTABLE ${MPIEXEC_POSTFLAGS} ARGS
where EXECUTABLE is the MPI program, and ARGS are the arguments to
pass to the MPI program.
Advanced variables for using MPI¶
The module can perform some advanced feature detections upon explicit request.
Important notice: The following checks cannot be performed without executing an MPI test program.
Consider the special considerations for the behavior of try_run() during cross compilation.
Moreover, running an MPI program can cause additional issues, like a firewall notification on some systems.
You should only enable these detections if you absolutely need the information.
If the following variables are set to true, the respective search will be performed:
MPI_DETERMINE_Fortran_CAPABILITIESDetermine for all available Fortran bindings what the values of
MPI_SUBARRAYS_SUPPORTEDandMPI_ASYNC_PROTECTS_NONBLOCKINGare and make their values available asMPI_Fortran_<binding>_SUBARRAYSandMPI_Fortran_<binding>_ASYNCPROT, where<binding>is one ofF77_HEADER,F90_MODULEandF08_MODULE.MPI_DETERMINE_LIBRARY_VERSIONFor each language, find the output of
MPI_Get_library_versionand make it available asMPI_<lang>_LIBRARY_VERSION_STRING. This information is usually tied to the runtime component of an MPI implementation and might differ depending on<lang>. Note that the return value is entirely implementation defined. This information might be used to identify the MPI vendor and for example pick the correct one of multiple third party binaries that matches the MPI vendor.
Backward Compatibility¶
Deprecated since version 3.10.
For backward compatibility with older versions of FindMPI, these variables are set:
MPI_COMPILER MPI_LIBRARY MPI_EXTRA_LIBRARY
MPI_COMPILE_FLAGS MPI_INCLUDE_PATH MPI_LINK_FLAGS
MPI_LIBRARIES
In new projects, please use the MPI_<lang>_XXX equivalents.
Additionally, the following variables are deprecated:
MPI_<lang>_COMPILE_FLAGSUse
MPI_<lang>_COMPILE_OPTIONSandMPI_<lang>_COMPILE_DEFINITIONSinstead.MPI_<lang>_INCLUDE_PATHFor consumption use
MPI_<lang>_INCLUDE_DIRSand for specifying folders useMPI_<lang>_ADDITIONAL_INCLUDE_DIRSinstead.MPIEXECUse
MPIEXEC_EXECUTABLEinstead.