MPI_Init(3)							      LAM/MPI							       MPI_Init(3)

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.

       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 por-
       table 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).

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 catches several signals 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.  This scheme prevents nodes (remote nodes, especially)
       from silently dying and hanging the remaining MPI ranks because of unfinished communications - a very confusing	situation  when  debugging
       parallel programs.

       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.  If users do not wish to have LAM catch signals (a bad idea!), they should set their
       handlers after 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 any-
       thing 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 con-
       structors 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

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/sow-
       ing/sowing.tar.gz ), the initial formatting, and some initial text for most of the MPI-1 man pages.

LOCATION

       init.c

LAM
/MPI 6.5.8							    11/10/2002							       MPI_Init(3)