detect.m File Reference

Go to the source code of this file.

Functions
function	detect (in vendor)
	Return the MPI image count and current image ID (e.g., MPI rank + 1) and the MPI library name as it appears in the ParaMonte library path and the corresponding MPI-parallel ParaMonte library path . More...

Function Documentation

detect()

function detect

(

in

vendor

)

Return the MPI image count and current image ID (e.g., MPI rank + 1) and the MPI library name as it appears in the ParaMonte library path and the corresponding MPI-parallel ParaMonte library path .

This function attempts to detect the invocation of the current MATLAB session via checking the runtime behavior of the mpiexec binary MPI launcher instance.

Output values interpretation

1. If the output mpiname is set to an empty string "", meaning that strcmp(mpiname, "") yields true, then the algorithm has failed, implying that the current application is likely to have been launched by via an mpiexec binary whose MPI library is supported by the ParaMonte library.
   
2. If the output mpiname is set to an non-empty string, which must be the name of an MPI library vendor used within ParaMonte,
   then an instance of the corresponding MPI library likely exists on the current system and its mpiexec binary has been used to launch the current application in parallel.
   If so,
   
   1. A value of 0 for either of the output values nproc and rankp1 implies the algorithm failed to infer the corresponding parameters.
      
   2. A non-zero positive value for either or both of the output values nproc and rankp1 implies that the mpiexec MPI launcher binary of the corresponding MPI library might have been used to launch MATLAB and its might have been used to launch MATLAB.
      
      1. A non-zero positive value other than 1 for the output nproc guarantees that the mpiexec launcher has been used to launch MATLAB with the specified nproc number of MPI images (processes).
         

Parameters

[in]

vendor

: The input scalar MATLAB string, containing the MPI library vendor supported by the ParaMonte library. Possible values are: OpenMPI, representing the OpenMPI library. MPICH, representing the MPICH MPI library. Intel, representing the Intel MPI library. any, representing any available MPI library. or any other informal name returned by the ParaMonte MATLAB function pm.lib.mpi.name(). Note that all values are case-insensitive. (**optional, default = "any".)

Returns

mpiname : The output scalar MATLAB string containing the MPI library name as it appears in the ParaMonte library path.
An output value of "" implies the algorithm failed to detect a ParaMonte-compatible MPI library invoked or installed on the system.
nproc : The output scalar MATLAB non-negative whole number containing the number of MPI images in the current invocation of the mpiexec binary MPI launcher.
An output value of 0 implies the algorithm failed to detect a ParaMonte-compatible MPI library or failed to infer the image count.
rankp1 : The output scalar MATLAB non-negative whole number containing the image ID (e.g., MPI rank + 1) of the current MPI image in the current invocation of the mpiexec binary MPI launcher.
An output value of 0 implies the algorithm failed to detect a ParaMonte-compatible MPI library or failed to infer the image count.
Note that the image ID always starts at 1, unlike the MPI rank.
The argument rankp1 stands for rank + 1.

Possible calling interfaces ⛓

[mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect();
[mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect(vendor);

Warning

This routine must be called before the MPI library is finalized by any other application.
Example applications that finalize the MPI library upon return includes the ParaMonte MPI-parallel samplers.
However, each application offers an option to prevent the default finalization of the MPI library.
For this reason, the results of this function are saved within the function for subsequent usage after the first call.

Note

This function internally uses a persistent MATLAB struct to store the results for the default input value for vendor to expedite future inquiries using this function.
Specifying an input argument value will always

Example usage ⛓

cd(fileparts(mfilename('fullpath'))); % Change working directory to source code directory.
addpath('../../../../../'); % Add the ParaMonte library root directory to the search path.
 
disp('[mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect()')
      [mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect()
disp("")
 
disp('[mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("impi")')
      [mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("impi")
disp("")
 
disp('[mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("INTEL")')
      [mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("INTEL")
disp("")
 
disp('[mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("intel")')
      [mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("intel")
disp("")
 
disp('[mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("ompi")')
      [mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("ompi")
disp("")
 
disp('[mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("openmpi")')
      [mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("openmpi")
disp("")
 
disp('[mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("open-mpi")')
      [mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("open-mpi")
disp("")
 
disp('[mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("mpich")')
      [mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("mpich")
disp("")
 
disp('[mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("mpi")')
      [mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("mpi")

Example output ⛓

[mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect()
mpiname = 
    ""
nproc =
     0
rankp1 =
     0
[mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("impi")
mpiname = 
    ""
nproc =
     0
rankp1 =
     0
[mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("INTEL")
mpiname = 
    ""
nproc =
     0
rankp1 =
     0
[mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("intel")
mpiname = 
    ""
nproc =
     0
rankp1 =
     0
[mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("ompi")
mpiname = 
    ""
nproc =
     0
rankp1 =
     0
[mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("openmpi")
mpiname = 
    ""
nproc =
     0
rankp1 =
     0
[mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("open-mpi")
mpiname = 
    ""
nproc =
     0
rankp1 =
     0
[mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("mpich")
mpiname = 
    ""
nproc =
     0
rankp1 =
     0
[mpiname, nproc, rankp1] = pm.lib.mpi.runtime.detect("mpi")
mpiname = 
    ""
nproc =
     0
rankp1 =
     0

Todo:

High Priority: The internals of this function can be improved for better efficiency and less redundancy.

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, 2:27 AM Monday, November 11, 2024, Dallas, TX