Man Linux: Main Page and Category List

NAME

       MPI_Init -  Initialize the MPI execution environment

SYNOPSIS

       #include <mpi.h>
       int MPI_Init(int *pargc, char ***pargv)

INPUT PARAMETERS

       pargc  - Pointer to the number of arguments
       pargv  - Pointer to the argument vector

NOTES

       MPI   specifies  no  command-line  arguments  but  does  allow  an  MPI
       implementation to make use of them.  LAM/MPI neither uses nor adds  any
       values  to  the argc and argv parameters.  As such, it is legal to pass
       NULL for both argc and argv in LAM/MPI.

       Instead,  LAM/MPI  relies  upon  the  mpirun  command  to  pass   meta-
       information  between  nodes  in order to start MPI programs (of course,
       the LAM daemons must have previously been  launched  with  the  lamboot
       command).   As such, every rank in MPI_COMM_WORLD will receive the argc
       and argv that was specified with the mpirun  command  (either  via  the
       mpirun  command line or an app schema) as soon as main begins.  See the
       mpirun (1) man page for more information.

       If mpirun is not used to start MPI programs, the resulting process will
       be rank 0 in MPI_COMM_WORLD , and MPI_COMM_WORLD will have a size of 1.
       This is known as a "singleton"  MPI.   It  should  be  noted  that  LAM
       daemons  are still used for singleton MPI programs - lamboot must still
       have been successfully executed before running a singleton process.

       LAM/MPI takes care to ensure that the  normal  Unix  process  model  of
       execution  is  preserved: no extra threads or processes are forked from
       the user's process.  Instead, the LAM daemons are used for all  process
       management  and  meta-environment  information.   Consequently, LAM/MPI
       places no restriction on what may be invoked before MPI_INIT* or  after
       MPI_FINALIZE  ;  this  is not a safe assumption for those attempting to
       write portable MPI programs - see "Portability Concerns", below.

       MPI  mandates  that  the   same   thread   must   call   MPI_INIT   (or
       MPI_INIT_THREAD ) and MPI_FINALIZE .

       Note  that  the  Fortran  binding  for  this routine has only the error
       return argument ( MPI_INIT(ierror) ).

       Because the Fortran and C versions of MPI_INIT are different, there  is
       a  restriction  on  who can call MPI_INIT .  The version (Fortran or C)
       must match the main program.  That is, if the main  program  is  in  C,
       then  the C version of MPI_INIT must be called.  If the main program is
       in Fortran, the Fortran version must be called.

       LAM/MPI uses the value of argv[0] to identify a process in many of  the
       user-level  helper  applications  (mpitask  and  mpimsg,  for example).
       Fortran programs are generally identified as "LAM_MPI_Fortran_program".
       However,  this  name  can be overridden for Fortran programs by setting
       the environment variable "LAM_MPI_PROCESS_NAME".

       On exit from this routine, all  processes  will  have  a  copy  of  the
       argument  list.   This  is not required by the MPI standard, and truely
       portable codes should not rely on it.  This is provided as a service by
       this implementation (an MPI implementation is allowed to distribute the
       command line arguments but is not required to).

THREADING

       Applications using MPI_INIT are  effectively  invoking  MPI_INIT_THREAD
       with  a  requested thread support of MPI_THREAD_SINGLE .  However, this
       may be overridden with the LAM_MPI_THREAD_LEVEL  environment  variable.
       If  set,  this  variable  replaces the default MPI_THREAD_SINGLE value.
       The following values are allowed

       0: Corresponds to MPI_THREAD_SINGLE

       1: Corresponds to MPI_THREAD_FUNNELED

       2: Corresponds to MPI_THREAD_SERIALIZED

       3: Corresponds to MPI_THREAD_MULTIPLE

       See MPI_Init_thread(3) for more information on thread level support  in
       LAM/MPI.

PREDEFINED ATTRIBUTES

       LAM/MPI  defines all required predefined attributes on MPI_COMM_WORLD .
       Some values are LAM-specific, and require explanation.

       MPI_UNIVERSE_SIZE

       This is an MPI-required attribute.  It is set to an integer whose value
       indicates  how  many  CPUs  LAM  was  booted  with.   See  bhost(5) and
       lamboot(1) for more details on how to specify multiple CPUs  per  node.
       Note  that this may be larger than the number of CPUs in MPI_COMM_WORLD
       .

       LAM_UNIVERSE_NCPUS

       This is a LAM-specific attribute -- it will not be defined in other MPI
       implementations.   It  is actually just a synonym for MPI_UNIVERSE_SIZE
       -- it contains the number of CPUs in the current  LAM  universe.   Note
       that this may be larger than the number of CPUs in MPI_COMM_WORLD .

       LAM_UNIVERSE_NNODES

       This is a LAM-specific attribute -- it will not be defined in other MPI
       implementations.  It indicates the total number of nodes in the current
       LAM  universe  (which  may be different from the total number of CPUs).
       Node that this may be larger than the number of nodes in MPI_COMM_WORLD
       .

SIGNALS USED

       The  LAM implementation of MPI uses, by default, SIGUSR2 .  This may be
       changed when LAM is compiled, however, with the  --with-signal  command
       line   switch   to   LAM's   configure  script.   Consult  your  system
       administrator to see if they specified a different signal when LAM  was
       installed.

       LAM/MPI  does not catch any other signals in user code, by default.  If
       a process terminates due to a signal, the mpirun will  be  notified  of
       this  and will print out an appropriate error message and kill the rest
       of the user MPI application.

       This behavior can be overridden (mainly for  historical  reasons)  with
       the  "-sigs"  flag  to  mpirun  .   When  "-sigs" is used, LAM/MPI will
       effectively transfer the signal-handling code from mpirun to  the  user
       program.   Signal  handlers  will  be  installed  during  MPI_INIT  (or
       MPI_INIT_THREAD ) for the purpose of  printing  error  messages  before
       invoking  the  next  signal  handler.  That is, LAM "chains" its signal
       handler to be executed before the signal handler that was already  set.

       Therefore,  it  is safe for users to set their own signal handlers.  If
       they wish the LAM signal handlers to be executed as well, users  should
       set their handlers before MPI_INIT* is invoked.

       LAM/MPI catches the following signals

       SIGSEGV , SIGBUS , SIGFPE , SIGILL

       All  other  signals  are unused by LAM/MPI, and will be passed to their
       respective signal handlers.

PORTABILITY CONCERNS

       Portable MPI programs cannot assume the same  process  model  that  LAM
       uses  (i.e.,  essentially  the  same  as  POSIX).  MPI does not mandate
       anything before MPI_INIT (or  MPI_INIT_THREAD  ),  nor  anything  after
       MPI_FINALIZE  executes.   Different  MPI implementations make different
       assumptions; some fork auxillary threads  and/or  processes  to  "help"
       with  the  MPI  run-time  environment  (this  may  interfere  with  the
       constructors and destructors of global C++ objects, particularly in the
       case  where  using atexit() or onexit(), for example).  As such, if you
       are  writing  a  portable  MPI  program,  you  cannot  make  the   same
       assumptions that LAM/MPI does.

       In general, it is safest to call MPI_INIT (or MPI_INIT_THREAD ) as soon
       as possible after main begins, and call MPI_FINALIZE immediately before
       the program is supposed to end.  Consult the documentation for each MPI
       implementation for their intialize and finalize behavior.

ERRORS

       If an error occurs in an MPI function, the current MPI error handler is
       called  to  handle  it.   By default, this error handler aborts the MPI
       job.  The error handler may be changed with  MPI_Errhandler_set  ;  the
       predefined  error  handler MPI_ERRORS_RETURN may be used to cause error
       values to be returned (in C and Fortran; this  error  handler  is  less
       useful  in  with  the  C++  MPI bindings.  The predefined error handler
       MPI::ERRORS_THROW_EXCEPTIONS should be used in C++ if the  error  value
       needs  to  be recovered).  Note that MPI does not guarantee that an MPI
       program can continue past an error.

       All MPI routines (except MPI_Wtime and  MPI_Wtick  )  return  an  error
       value;  C routines as the value of the function and Fortran routines in
       the last argument.  The C++  bindings  for  MPI  do  not  return  error
       values;  instead,  error values are communicated by throwing exceptions
       of type MPI::Exception (but  not  by  default).   Exceptions  are  only
       thrown if the error value is not MPI::SUCCESS .

       Note  that  if  the MPI::ERRORS_RETURN handler is set in C++, while MPI
       functions will return upon an error, there will be no  way  to  recover
       what the actual error value was.
       MPI_SUCCESS
              - No error; MPI routine completed successfully.
       MPI_ERR_OTHER
              -  This  error  class  is  associated  with  an  error code that
              indicates that an attempt was made to  call  MPI_INIT  a  second
              time.  MPI_INIT may only be called once in a program.
       MPI_ERR_OTHER
              -  Other  error;  use  MPI_Error_string  to get more information
              about this error code.

SEE ALSO

       MPI_Init_thread, MPI_Finalize, lamboot, mpirun, lamhalt, lamssi

MORE INFORMATION

       For more information, please see the official MPI Forum web site, which
       contains  the  text  of  both  the  MPI-1  and  MPI-2 standards.  These
       documents contain detailed information about each MPI function (most of
       which is not duplicated in these man pages).

       http://www.mpi-forum.org/

ACKNOWLEDGEMENTS

       The  LAM Team would like the thank the MPICH Team for the handy program
       to       generate        man        pages        ("doctext"        from
       ftp://ftp.mcs.anl.gov/pub/sowing/sowing.tar.gz     ),    the    initial
       formatting, and some initial text for most of the MPI-1 man pages.

LOCATION

       init.c