Provided by: lam-mpidoc_7.1.4-7.1build2_all bug

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