Updated manuals to include recent changes:
authorChao Huang <chuang10@uiuc.edu>
Sat, 19 Jul 2003 03:37:28 +0000 (03:37 +0000)
committerChao Huang <chuang10@uiuc.edu>
Sat, 19 Jul 2003 03:37:28 +0000 (03:37 +0000)
1. MPI_Checkpoint completed
2. Processor topology functions completed
3. Non-blocking version of collective function calls
4. Added several other functions

doc/ampi/manual.tex

index bb7fe0d546df27ede66c6e080495d0485005312e..54c58740c1117b9db074d650d016b2e051a812d0 100644 (file)
@@ -7,7 +7,8 @@
 \credits{
 AMPI has been developed by Milind Bhandarkar with inputs from Gengbin Zheng and
 Orion Lawlor. The derived data types (DDT) library, which AMPI uses for the
-derived data types support, has been developed by Neelam Saboo.
+derived data types support, has been developed by Neelam Saboo. The current 
+version of AMPI is maintained by Chao Huang.
 }
 
 \begin{document}
@@ -16,9 +17,10 @@ derived data types support, has been developed by Neelam Saboo.
 \section{Introduction}
 
 This manual describes Adaptive MPI~(\ampi{}), which is an implementation of a
-significant subset of MPI 1.1 standard over \charmpp{}. \charmpp{} is a
-\CC{}-based parallel programming library developed by Prof. L. V. Kale and his
-students over the last 10 years at University of Illinois.
+significant subset\footnote{Currently, 110 MPI-1.1 Standard functions have 
+been implemented.} of MPI-1.1 Standard over \charmpp{}. \charmpp{} is a
+\CC{}-based parallel programming library developed by Prof. L. V. Kal\'{e} 
+and his students over the last 10 years at University of Illinois.
 
 We first describe our philosophy behind this work (why we do what we do).
 Later we give a brief introduction to \charmpp{} and rationale for \ampi{}
@@ -35,7 +37,7 @@ code appropriate numerical methods, decide and implement the proper input and
 output data formats, perform visualizations, and be concerned with correctness
 and efficiency of the programs. It becomes even more complex for multi-physics
 coupled simulations such as the solid propellant rocket simulation application.  
-Our philosophy is to lessen the burden of the application developer by
+Our philosophy is to lessen the burden of the application developers by
 providing advanced programming paradigms and versatile runtime systems that can
 handle many common performance concerns automatically and let the application
 programmers focus on the actual application content.
@@ -135,7 +137,7 @@ advantage of dynamic load balancing. This is indeed impractical. However,
 \converse{} -- the runtime system of \charmpp{} -- came to our rescue here,
 since it supports interoperability between different parallel programming
 paradigms such as parallel objects and threads. Using this feature, we
-developed \ampi{}, an implementation of a significant subset of MPI 1.1
+developed \ampi{}, an implementation of a significant subset of MPI-1.1
 standard over \charmpp{}.  \ampi{} is described in the next section.
 
 \section{AMPI}
@@ -197,9 +199,9 @@ Since the subroutine arguments are passed on a stack, which is not shared
 across all threads, each subroutine, when executing within a thread operates on
 a private copy of the global variables. 
 
-This scheme is demonstrated in the following examples. The original
-Fortran 90 code contains a module \texttt{shareddata}. This module is used in
-the main program and a subroutine \texttt{subA}.
+This scheme is demonstrated in the following examples. The original Fortran 90 
+code contains a module \texttt{shareddata}. This module is used in the main 
+program and a subroutine \texttt{subA}.
 
 \begin{alltt}
 !FORTRAN EXAMPLE
@@ -340,76 +342,85 @@ command line) and stacks do not grow dynamically.
 
 \subsection{AMPI Status}
 
-Currently the following subset of MPI 1.1 standard is supported in \ampi{}.
+Currently the following subset of MPI-1.1 standard is supported in \ampi{}.
 
 \begin{alltt}
-================================================================================================
-Point-to-point      Collective         Groups, Contexts          Environment      Extensions*
-                                       and Communicators         Management
-================================================================================================
-MPI_Send            MPI_Barrier        MPI_Group_size            MPI_Error_string MPI_Migrate
-MPI_Recv            MPI_Bcast          MPI_Group_rank            MPI_Wtime        MPI_Checkpoint
-MPI_Get_count       MPI_Gather         MPI_Group_translate_ranks MPI_Init         MPI_Restart
-MPI_Bsend           MPI_Gatherv        MPI_Group_compare         MPI_Initialized  MPI_Register
-MPI_Ssend           MPI_Scatter        MPI_Comm_group            MPI_Finalize     MPI_Get_userdata
-MPI_Buffer_attach   MPI_Scatterv       MPI_Group_union           MPI_Abort        MPI_Ireduce
-MPI_Buffer_detach   MPI_Allgather      MPI_Group_intersection
-MPI_Isend           MPI_Allgatherv     MPI_Group_difference
-MPI_Ibsend          MPI_Alltoall       MPI_Group_incl
-MPI_Issend          MPI_Alltoallv      MPI_Group_excl
-MPI_Irecv           MPI_Reduce         MPI_Group_range_incl
-MPI_Wait            MPI_Allreduce      MPI_Group_range_excl
-MPI_Waitany         MPI_Reduce_scatter MPI_Group_free
-MPI_Waitall                            MPI_Comm_create
-MPI_Test                               MPI_Comm_size
-MPI_Testall                            MPI_Comm_rank
-MPI_Iprobe                             MPI_Comm_dup
-MPI_Probe                              MPI_Comm_split
-MPI_Send_init                          MPI_Comm_free
-MPI_Recv_init
-MPI_Start
-MPI_Sendrecv
-MPI_Sendrecv_replace
-MPI_Type_contiguous
-MPI_Type_vector
-MPI_Type_hvector
-MPI_Type_indexed
-MPI_Type_hindexed
-MPI_Type_struct
-MPI_Type_commit
-MPI_Type_free
+=============================================================================================
+Point-to-point     Collective         Groups, Contexts          Processor
+                                      and Communicators         Topology
+=============================================================================================
+MPI_Send           MPI_Barrier        MPI_Group_size            MPI_Cart_create
+MPI_Recv           MPI_Bcast          MPI_Group_rank            MPI_Dims_create
+MPI_Get_count      MPI_Gather         MPI_Group_translate_ranks MPI_Graph_create
+MPI_Bsend          MPI_Gatherv        MPI_Group_compare         MPI_Topo_test
+MPI_Rsend          MPI_Scatter        MPI_Comm_group            MPI_Cartdim_get
+MPI_Ssend          MPI_Scatterv       MPI_Group_union           MPI_Cart_get
+MPI_Buffer_attach  MPI_Allgather      MPI_Group_intersection    MPI_Cart_rank
+MPI_Buffer_detach  MPI_Allgatherv     MPI_Group_difference      MPI_Cart_coords
+MPI_Isend          MPI_Alltoall       MPI_Group_incl            MPI_Cart_shift
+MPI_Ibsend         MPI_Alltoallv      MPI_Group_excl            MPI_Cart_sub
+MPI_Issend         MPI_Reduce         MPI_Group_range_incl      MPI_Cart_map
+MPI_Irecv          MPI_Allreduce      MPI_Group_range_excl      MPI_Graphdims_get
+MPI_Wait           MPI_Reduce_scatter MPI_Group_free            MPI_Graph_get
+MPI_Waitany                           MPI_Comm_create           MPI_Graph_neighbors_count
+MPI_Waitall                           MPI_Comm_size             MPI_Graph_neighbors
+MPI_Waitsome                          MPI_Comm_rank             MPI_Graph_map
+MPI_Test                              MPI_Comm_dup
+MPI_Testall                           MPI_Comm_split
+MPI_Testsome                          MPI_Comm_free
+MPI_Request_free
+MPI_Cancel
+MPI_Iprobe
+MPI_Probe
+MPI_Send_init
+MPI_Bsend_init
+MPI_Ssend_init
+MPI_Rsend_init
+MPI_Recv_init                        ========================================================
+MPI_Start                             Environment               AMPI Extensions*
+MPI_Startall                          Management
+MPI_Sendrecv                         ========================================================
+MPI_Sendrecv_replace                  MPI_Error_string          MPI_Migrate
+MPI_Type_contiguous                   MPI_Wtime                 MPI_Checkpoint
+MPI_Type_vector                       MPI_Wtick                 MPI_Restart
+MPI_Type_hvector                      MPI_Init                  MPI_Register
+MPI_Type_indexed                      MPI_Initialized           MPI_Get_userda
+MPI_Type_hindexed                     MPI_Finalize              MPI_Ialltoall
+MPI_Type_struct                       MPI_Abort                 MPI_Iallgather
+MPI_Type_commit                                                 MPI_Iallreduce
+MPI_Type_free                                                   MPI_Ireduce
 MPI_Type_extent
 MPI_Type_size
+MPI_Type_lb
+MPI_Type_ub
+MPI_Address
+MPI_Get_elements
 MPI_Pack
 MPI_Unpack
 MPI_Pack_size
-================================================================================================
+=============================================================================================
 * AMPI extensions are explained later in this manual.
 \end{alltt}
 
-Following MPI 1.1 basic datatypes are supported in \ampi{}. (Some are not available in
+Following MPI-1.1 basic datatypes are supported in \ampi{}. (Some are not available in
 Fortran binding. Refer to MPI-1.1 Standard for details.)
 \begin{alltt}
-MPI_DATATYPE_NULL  MPI_CHAR           MPI_UNSIGNED_SHORT  MPI_LONG_INT
-MPI_DOUBLE         MPI_BYTE           MPI_UNSIGNED        MPI_2INT
-MPI_INT            MPI_PACKED         MPI_UNSIGNED_LONG   MPI_SHORT_INT
-MPI_FLOAT          MPI_SHORT          MPI_LONG_DOUBLE     MPI_LONG_DOUBLE_INT
-MPI_COMPLEX        MPI_LONG           MPI_FLOAT_INT       MPI_2FLOAT
-MPI_LOGICAL        MPI_UNSIGNED_CHAR  MPI_DOUBLE_INT      MPI_2DOUBLE
+MPI_DATATYPE_NULL  MPI_BYTE            MPI_UNSIGNED_LONG MPI_LONG_DOUBLE_INT
+MPI_DOUBLE         MPI_PACKED          MPI_LONG_DOUBLE   MPI_2FLOAT
+MPI_INT            MPI_SHORT           MPI_FLOAT_INT     MPI_2DOUBLE
+MPI_FLOAT          MPI_LONG            MPI_DOUBLE_INT    MPI_LB
+MPI_COMPLEX        MPI_UNSIGNED_CHAR   MPI_LONG_INT      MPI_UB
+MPI_LOGICAL        MPI_UNSIGNED_SHORT  MPI_2INT
+MPI_CHAR           MPI_UNSIGNED        MPI_SHORT_INT
 \end{alltt}
 
-Following MPI 1.1 reduction operations are supported in \ampi{}.
+Following MPI-1.1 reduction operations are supported in \ampi{}.
 
 \begin{alltt}
 MPI_MAX   MPI_MIN   MPI_SUM   MPI_PROD  MPI_MAXLOC  MPI_MINLOC
 MPI_LAND  MPI_LOR   MPI_LXOR  MPI_BAND  MPI_BOR     MPI_BXOR
 \end{alltt}
 
-Also, unlike the MPI 1.1 standard, the Fortran90 statement ``\texttt{use mpi}'' 
-should not be used.
-Instead one needs to put the ``\texttt{use ampi}'' statement in Fortran
-program units that use \ampi{}.
-
 \subsection{Extensions for Migrations}
 
 For MPI chunks to migrate, we have added a few calls to \ampi{}. These include
@@ -647,19 +658,21 @@ restarted on a different processor. Using the \emph{same} subroutines, it
 is also possible to save the state of the program to disk, so that if the 
 program were to crash abruptly, or if the allocated time for the program
 expires before completing execution, the program can be restarted from the
-previously checkpointed state. Thus, the pack-unpack subroutines act as the key facility for checkpointing in addition to their usual role for migration.
-
-A subroutine, \texttt{MPI\_Checkpoint} has been added to AMPI. This subroutine
-takes a directory name as its argument. Every chunk in the program needs to
-call this subroutine and specify the same directory name. (Typically, in an
+previously checkpointed state. Thus, the pack-unpack subroutines act as the 
+key facility for checkpointing in addition to their usual role for migration.
+
+A subroutine for checkpoint purpose has been added to AMPI:
+\texttt{void MPI\_Checkpoint(char *dirname);}
+This subroutine takes a directory name as its argument. It is a collective 
+function, meaning every virtual processor in the program needs to call this 
+subroutine and specify the same directory name. (Typically, in an
 iterative AMPI program, the iteration number, converted to a character string,
 can serve as a checkpoint directory name.) This directory is created, and the
 entire state of the program is checkpointed to this directory.  One can restart
 the program from the checkpointed state by specifying \texttt{"+restart
-dirname"} on the command-line.
-
-This extension is under active refinement and a stable version will be available
-very soon.
+dirname"} on the command-line. This capability is powered by the \charmpp{} 
+runtime system. For more information about \charmpp{} checkpoint/restart
+mechanism please refer to \charmpp{} manual. 
 
 \subsection{Extensions for Interoperability}
 
@@ -845,15 +858,9 @@ libraries needed by \ampi{}), specify \verb+<target>+ to be \verb+AMPI+. And
 script.  Common compile time options such as \texttt{-g, -O, -Ipath, -Lpath,
 -llib} are accepted. 
 
-To build a debugging version of \ampi{}, use the option:
-\begin{alltt}
--g
-\end{alltt}
-
-To build a production version of \ampi{}, use the options:
-\begin{alltt}
--O -DCMK_OPTIMIZE=1
-\end{alltt}
+To build a debugging version of \ampi{}, use the option: ``\texttt{-g}''. 
+To build a production version of \ampi{}, use the options: ``\texttt{-O 
+-DCMK\_OPTIMIZE=1}''.
 
 \verb+<version>+ depends on the machine, operating system, and the underlying
 communication library one wants to use for running \ampi{} programs.
@@ -879,6 +886,14 @@ same way. For example:
 > charmc -language ampi -o pgm pgm.o -lm -O3 
 \end{alltt}
 
+Shortcuts to the AMPI compiler are provided. If you have added charm/bin 
+into your \$PATH environment variable, simply type \emph{mpicc, mpiCC, 
+mpif77,} and \emph{mpif90} as provided by other MPI implementations.
+
+\begin{alltt}
+> mpicc -c pgm.c -g
+\end{alltt}
+
 \subsection{Running}
 \charmpp{} distribution contains a script called \texttt{charmrun} that makes
 the job of running \ampi{} programs portable and easier across all parallel