ampi manual changes and additions
[charm.git] / doc / ampi / manual.tex
1 \documentclass[10pt]{article}
2 \usepackage{../pplmanual,pst-node}
3 \input{../pplmanual}
4
5 \title{Adaptive MPI Manual}
6 \version{1.0}
7 \credits{
8 AMPI has been developed by Milind Bhandarkar with inputs from Gengbin Zheng and
9 Orion Lawlor. The derived data types (DDT) library, which AMPI uses for the
10 derived data types support, has been developed by Neelam Saboo. The current 
11 version of AMPI is maintained by Chao Huang.
12 }
13
14 \begin{document}
15 \maketitle
16
17 \section{Introduction}
18
19 This manual describes Adaptive MPI~(\ampi{}), which is an implementation of a
20 significant subset\footnote{Currently, 110 MPI-1.1 Standard functions have 
21 been implemented.} of MPI-1.1 Standard over \charmpp{}. \charmpp{} is a
22 \CC{}-based parallel programming library being developed by Prof. L. V. Kal\'{e} 
23 and his students back from 1992 until now at University of Illinois.
24
25 We first describe our philosophy behind this work (why we do what we do).
26 Later we give a brief introduction to \charmpp{} and rationale for \ampi{}
27 (tools of the trade). We then describe \ampi{} in detail. Finally we summarize the
28 changes required for original MPI codes to get them working with \ampi{}
29 (current state of our work). Appendices contain the gory details of installing
30 \ampi{}, building and running \ampi{} programs.
31
32 \subsection{Overview}
33
34 Developing parallel Computational Science and Engineering (CSE) applications is
35 a complex task. One has to implement the right physics, develop or choose and
36 code appropriate numerical methods, decide and implement the proper input and
37 output data formats, perform visualizations, and be concerned with correctness
38 and efficiency of the programs. It becomes even more complex for multi-physics
39 coupled simulations such as the solid propellant rocket simulation application. In addition, many applications
40  are dynamic and adaptively refined so load imbalance is a major challenge.
41 Our philosophy is to lessen the burden of the application developers by
42 providing advanced programming paradigms and versatile runtime systems that can
43 handle many common programming and performance concerns automatically and let the application
44 programmers focus on the actual application content.
45
46 Many of these concerns can be addressed using processor virtualization and 
47 over-decomposition philosophy of \charmpp{}. Thus, the developer only sees 
48 virtual processors and lets the runtime system deal with underlying physical 
49 processors. This is implemented in \ampi{} by mapping MPI ranks to \charmpp{} user-level
50  threads as illustrated in Figure\ref{fig_virt}. As an immediate and simple benefit, the programmer can use as 
51 many virtual processors ("MPI ranks") as the problem can be easily decomposed
52  to them. For example, suppose the problem domain has $n*2^n$ parts that can be
53   easily distributed but programming for general number of MPI processes is burdensome, 
54   then the developer can have $n*2^n$ virtual processors on any number of physical ones using \ampi{}.
55   
56 \begin{figure}[h]
57 \centering
58 \includegraphics[width=4.6in]{figs/virtualization.png}
59 \caption{MPI processes are implemented as user-level threads in \ampi{}}
60 \label{fig_virt}
61 \end{figure}
62
63 \ampi{}'s execution model consists of multiple user-level threads per process and,
64 typically, there is one process per physical processor. \charmpp{} scheduler coordinates
65 execution of these threads (also called Virtual Processors or VPs) and controls execution as shown in Figure \ref{fig_ratio}. These
66 VPs can also migrate between processors because of load balancing or other reasons.
67 The number of VPs per processor specifies the virtualization ratio (degree of over-decomposition). For example, in Figure \ref{fig_ratio} virtualization ratio is four (there are four VPs per each processor). Figure \ref{fig_prac} show how the problem domain is over-decomposed in \ampi{}'s VPs as opposed to other MPI implementations.
68
69 \begin{figure}[h]
70 \centering
71 \includegraphics[width=1.8in]{figs/ratio.png}
72 \caption{VPs are managed by \charmpp{} scheduler}
73 \label{fig_ratio}
74 \end{figure}
75
76 \begin{figure}[h]
77 \centering
78 \includegraphics[width=4.6in]{figs/prac.png}
79 \caption{Problem domain is over-decomposed to more VPs}
80 \label{fig_prac}
81 \end{figure}
82
83 Another benefit of virtualization is communication and computation overlap which 
84 is automatically achieved without programming effort. Techniques such as software 
85 pipelining require significant programming 
86 effort to achieve this goal and improve performance. However, one can use \ampi{} to 
87 have more virtual processors than physical processors to overlap communication and 
88 computation. Each time a VP is blocked for communication, \charmpp{} scheduler
89  picks the next VP among those that are ready to execute. In this manner, while
90  some of the VPs of a physical processor are 
91 waiting for a message to arrive, others can continue their execution. Thus, performance 
92 will be improved without any change to the source code.
93
94 A potential benefit is that of better cache utilization. With over-decomposition, a smaller subdomain is accessed by a VP repeatedly in different function calls before getting blocked by communication and switching to another VP. That smaller subdomain may fit into cache if over-decomposition is enough. This concept is illustrated in Figure \ref{fig_cache} where each \ampi{} subdomain (such as 12) is smaller than corresponding MPI subdomain (such as 3) and may fit into cache memory. Thus, there is a potential performance improvement without changing the source code.
95
96 \begin{figure}[h]
97 \centering
98 \includegraphics[width=4.6in]{figs/cache.png}
99 \caption{Smaller subdomains may fit into cache and result in better performance}
100 \label{fig_cache}
101 \end{figure}
102
103 One important concern is that of load imbalance. New generation parallel applications are 
104 dynamically varying, meaning that processors' load is shifting during execution. In a dynamic simulation application
105 such as rocket simulation, burning  solid fuel, sub-scaling for a certain part
106 of the mesh, crack propagation, particle flows all contribute to load
107 imbalance. Centralized load balancing strategy built into an application is
108 impractical since each individual modules are developed almost independently by
109 various developers. In addition, embedding a load balancing strategy in the code 
110 complicates it and programming effort increases significantly. Thus, the runtime 
111 system support for load balancing becomes even more critical. Figure \ref{fig_migrate} shows migration of a VP because of load imbalance. For instance, this domain may correspond to a weather forecast model where there is a tornado in top-left side, which requires more computation to simulate. \ampi{} will then migrate VP 13 to balance the division of work across processors and improve performance. Note that incorporating this sort of load balancing inside the application code may take a lot of effort and complicates the code.
112
113 \begin{figure}[h]
114 \centering
115 \includegraphics[width=4.6in]{figs/migrate.png}
116 \caption{\ampi{} migrates VPs across processors for load balancing}
117 \label{fig_migrate}
118 \end{figure}
119
120 There are different load balancing strategies built into \charmpp{} that can be 
121 selected. Among those, some may fit better for an application depending on its 
122 characteristics. Moreover, one can write a new load balancer, best suited for an 
123 application, by the simple API provided inside \charmpp{} infrastructure. Our approach is
124 based on actual measurement of load information at runtime, and on migrating
125 computations from heavily loaded to lightly loaded processors.
126
127 For this approach to be effective, we need the computation to be split into
128 pieces many more in number than available processors. This allows us to
129 flexibly map and re-map these computational pieces to available processors.
130 This approach is usually called ``multi-domain decomposition''.
131
132 \charmpp{}, which we use as a runtime system layer for the work described here,
133 simplifies our approach. It embeds an elaborate performance tracing mechanism,
134 a suite of plug-in load balancing strategies, infrastructure for defining and
135 migrating computational load, and is interoperable with other programming
136 paradigms.
137
138 \subsection{Terminology}
139
140 \begin{description}
141
142 \item[Module] A module refers to either a complete program or a library with an
143 orchestrator subroutine\footnote{Like many software engineering terms, this
144 term is overused, and unfortunately clashes with Fortran 90 module that denotes
145 a program unit. We specifically refer to the later as ``Fortran 90 module'' to
146 avoid confusion.} . An orchestrator subroutine specifies the main control flow
147 of the module by calling various subroutines from the associated library and
148 does not usually have much state associated with it.
149
150 \item[Thread] A thread is a lightweight process that owns a stack and machine
151 registers including program counter, but shares code and data with other
152 threads within the same address space. If the underlying operating system
153 recognizes a thread, it is known as kernel thread, otherwise it is known as
154 user-thread. A context-switch between threads refers to suspending one thread's
155 execution and transferring control to another thread. Kernel threads typically
156 have higher context switching costs than user-threads because of operating
157 system overheads. The policy implemented by the underlying system for
158 transferring control between threads is known as thread scheduling policy.
159 Scheduling policy for kernel threads is determined by the operating system, and
160 is often more inflexible than user-threads. Scheduling policy is said to be
161 non-preemptive if a context-switch occurs only when the currently running
162 thread willingly asks to be suspended, otherwise it is said to be preemptive.
163 \ampi{} threads are non-preemptive user-level threads.
164
165 \item[Chunk] A chunk is a combination of a user-level thread and the data it
166 manipulates. When a program is converted from MPI to \ampi{}, we convert an MPI
167 process into a chunk. This conversion is referred to as chunkification.
168
169 \item[Object] An object is just a blob of memory on which certain computations
170 can be performed. The memory is referred to as an object's state, and the set
171 of computations that can be performed on the object is called the interface of
172 the object.
173
174 \end{description}
175
176 \section{\charmpp{}}
177
178 \charmpp{} is an object-oriented parallel programming library for \CC{}.  It
179 differs from traditional message passing programming libraries (such as MPI) in
180 that \charmpp{} is ``message-driven''. Message-driven parallel programs do not
181 block the processor waiting for a message to be received.  Instead, each
182 message carries with itself a computation that the processor performs on
183 arrival of that message. The underlying runtime system of \charmpp{} is called
184 \converse{}, which implements a ``scheduler'' that chooses which message to
185 schedule next (message-scheduling in \charmpp{} involves locating the object
186 for which the message is intended, and executing the computation specified in
187 the incoming message on that object). A parallel object in \charmpp{} is a
188 \CC{} object on which a certain computations can be asked to performed from
189 remote processors.
190
191 \charmpp{} programs exhibit latency tolerance since the scheduler always picks
192 up the next available message rather than waiting for a particular message to
193 arrive.  They also tend to be modular, because of their object-based nature.
194 Most importantly, \charmpp{} programs can be \emph{dynamically load balanced},
195 because the messages are directed at objects and not at processors; thus
196 allowing the runtime system to migrate the objects from heavily loaded
197 processors to lightly loaded processors. It is this feature of \charmpp{} that
198 we utilize for \ampi{}.
199
200 Since many CSE applications are originally written using MPI, one would have to
201 do a complete rewrite if they were to be converted to \charmpp{} to take
202 advantage of dynamic load balancing and other \charmpp{} benefits. This is indeed impractical. However,
203 \converse{} -- the runtime system of \charmpp{} -- came to our rescue here,
204 since it supports interoperability between different parallel programming
205 paradigms such as parallel objects and threads. Using this feature, we
206 developed \ampi{}, an implementation of a significant subset of MPI-1.1
207 standard over \charmpp{}.  \ampi{} is described in the next section.
208
209 \section{AMPI}
210
211 \ampi{} utilizes the dynamic load balancing and other capabilities of \charmpp{} by
212 associating a ``user-level'' thread with each \charmpp{} migratable object.
213 User's code runs inside this thread, so that it can issue blocking receive
214 calls similar to MPI, and still present the underlying scheduler an opportunity
215 to schedule other computations on the same processor. The runtime system keeps
216 track of computation loads of each thread as well as communication graph
217 between \ampi{} threads, and can migrate these threads in order to balance the
218 overall load while simultaneously minimizing communication overhead. 
219
220 \subsection{AMPI Status}
221
222 Currently all the MPI-1.1 Standard functions are supported in \ampi{}, with a
223 collection of our extentions explained in detail in this manual. One-sided
224 communication calls in MPI-2 are implemented, but they are not taking advantage
225 of RMA features yet. Also ROMIO\footnote{http://www-unix.mcs.anl.gov/romio/} 
226 has been integrated to support parallel I/O features. Link with {\tt -lampiromio}
227 to take advantage of this library.
228
229 Following MPI-1.1 basic datatypes are supported in \ampi{}. (Some are not 
230 available in Fortran binding. Refer to MPI-1.1 Standard for details.)
231 \begin{alltt}
232 MPI_DATATYPE_NULL  MPI_BYTE            MPI_UNSIGNED_LONG MPI_LONG_DOUBLE_INT
233 MPI_DOUBLE         MPI_PACKED          MPI_LONG_DOUBLE   MPI_2FLOAT
234 MPI_INT            MPI_SHORT           MPI_FLOAT_INT     MPI_2DOUBLE
235 MPI_FLOAT          MPI_LONG            MPI_DOUBLE_INT    MPI_LB
236 MPI_COMPLEX        MPI_UNSIGNED_CHAR   MPI_LONG_INT      MPI_UB
237 MPI_LOGICAL        MPI_UNSIGNED_SHORT  MPI_2INT
238 MPI_CHAR           MPI_UNSIGNED        MPI_SHORT_INT
239 \end{alltt}
240
241 Following MPI-1.1 reduction operations are supported in \ampi{}.
242
243 \begin{alltt}
244 MPI_MAX   MPI_MIN   MPI_SUM   MPI_PROD  MPI_MAXLOC  MPI_MINLOC
245 MPI_LAND  MPI_LOR   MPI_LXOR  MPI_BAND  MPI_BOR     MPI_BXOR
246 \end{alltt}
247
248 Following are AMPI extension calls, which will be explained in detail in this
249 manual.
250 \begin{alltt}
251 MPI_Migrate     MPI_Checkpoint  MPI_Restart     MPI_Register    MPI_Get_userdata
252 MPI_Ialltoall   MPI_Iallgather  MPI_Iallreduce  MPI_Ireduce     MPI_IGet
253 \end{alltt}
254
255
256 \subsection{Name for Main Program}
257
258 To convert an existing program to use AMPI, the main function or program may need to be renamed. The changes should be made as follows:
259
260 \subsubsection{Fortran}
261
262 You must declare the main program as a subroutine called ``MPI\_MAIN''. Do not declare the main subroutine as a \textit{program} because it will never be called by the AMPI runtime.
263
264 \begin{alltt}
265
266 program pgm -> subroutine MPI_Main\r
267         ...                                   ...\r
268 end program -> end subroutine
269 \end{alltt}
270
271 \subsubsection{C or C++}
272
273 The main function can be left as is, if \texttt{mpi.h} is included before the main function. This header file has a preprocessor macro that renames main, and the renamed version is called by the AMPI runtime by each thread.
274
275
276 \subsection{Global Variable Privatization}
277
278 For the before-mentioned benefits to be effective, one needs to map multiple
279 user-level threads onto each processor. 
280 Traditional MPI programs assume that the
281 entire processor is allocated to themselves, and that only one thread of
282 control exists within the process's address space. So, they may use global and static variables in the program.
283 However, global and static variables are problematic for multi-threaded environments such as \ampi{} or OpenMP.
284 This is because there is a single instance of those variables so they will be 
285 shared among different threads in the single address space and a wrong result may be produced by the program.
286 Figure \ref{fig_global} shows an example of a multi-threaded application with 
287 two threads in a single process. $var$ is a global or static variable in this 
288 example. Thread 1 assigns a value to it, then it gets blocked for communication 
289 and another thread can continue. Thereby, thread 2 is scheduled next and 
290 accesses $var$ which is wrong. Semantics of this program needs separate 
291 instances of $var$ for each of the threads. Thats where the need arises
292 to make some transformations to the original MPI program in order to run
293 correctly with \ampi{}.
294
295 \begin{figure}[h]
296 \centering
297 \includegraphics[width=4.6in]{figs/global.png}
298 \caption{Global or static variables are an issue for \ampi{}}
299 \label{fig_global}
300 \end{figure}
301
302 The basic transformation needed to port the MPI program to \ampi{} is
303 privatization of global variables.\footnote{Typical Fortran MPI programs
304 contain three types of global variables.
305
306 \begin{enumerate}
307
308 \item Global variables that are ``read-only''. These are either
309 \emph{parameters} that are set at compile-time. Or other variables that are
310 read as input or set at the beginning of the program and do not change during
311 execution. It is not necessary to privatize such variables.
312
313 \item Global variables that are used as temporary buffers. These are variables
314 that are used temporarily to store values to be accessible across subroutines.
315 These variables have a characteristic that there is no blocking call such as
316 \texttt{MPI\_recv} between the time the variable is set and the time it is ever
317 used. It is not necessary to privatize such variables either. 
318
319 \item True global variables. These are used across subroutines that contain
320 blocking receives and therefore possibility of a context switche between the
321 definition and use of the variable. These variables need to be privatized.
322
323 \end{enumerate}
324 }
325 With the MPI process model, each MPI node can keep a copy of its own
326 ``permanent variables'' -- variables that are accessible from more than one
327 subroutines without passing them as arguments.  Module variables, ``saved''
328 subroutine local variables, and common blocks in Fortran 90 belong to this
329 category. If such a program is executed without privatization on \ampi{}, all
330 the \ampi{} threads that reside on one processor will access the same copy of
331 such variables, which is clearly not the desired semantics.  To ensure correct
332 execution of the original source program, it is necessary to make such
333 variables ``private'' to individual threads. We are two choices: automatic 
334 global swapping and manual code modification.
335
336 \subsubsection{Automatic Globals Swapping}
337 Thanks to the ELF Object Format, we have successfully automated the procedure 
338 of switching the set of user global variables when switching thread contexts.
339 Executable and Linkable Format (ELF) is a common standard file format for Object Files in Unix-like operating systems.
340 ELF maintains a Global Offset Table (GOT) for globals so it is possible to\r
341 switch GOT contents at thread context-switch by the runtime system.\r
342
343
344 The only thing that the user needs to do is to set flag {\tt -swapglobals}
345 at compile and link time (e.g. ``ampicc Ðo prog prog.c -swapglobals"). It does not need 
346 any change to the source code and works with any language (C, C++, Fortran, etc).
347 However, it does not handle static variables and has a context switching overhead that grows with the number of global variables.
348 Currently, this feature only works on x86 and x86\_64
349  (e.g. amd64) platforms that fully support ELF. Thus, it may not work on PPC or
350   Itanium, or on some microkernels such as Catamount. When this feature does
351    not work for you,
352 you can try other ways of handling global or static variables, which are detailed in the
353 following sections.
354
355 \subsubsection{Manual Change}
356 We have employed a strategy of argument passing to do this privatization
357 transformation. That is, the global variables are bunched together in a
358 single user-defined type, which is allocated by each thread dynamically. Then a
359 pointer to this type is passed from subroutine to subroutine as an argument.
360 Since the subroutine arguments are passed on a stack, which is not shared
361 across all threads, each subroutine, when executing within a thread operates on
362 a private copy of the global variables. 
363
364 This scheme is demonstrated in the following examples. The original Fortran 90 
365 code contains a module \texttt{shareddata}. This module is used in the main 
366 program and a subroutine \texttt{subA}.
367
368 \begin{alltt}
369 !FORTRAN EXAMPLE
370 MODULE shareddata
371   INTEGER :: myrank
372   DOUBLE PRECISION :: xyz(100)
373 END MODULE
374
375 SUBROUTINE MPI_MAIN
376   USE shareddata
377   include 'mpif.h'
378   INTEGER :: i, ierr
379   CALL MPI_Init(ierr)
380   CALL MPI_Comm_rank(MPI_COMM_WORLD, myrank, ierr)
381   DO i = 1, 100
382     xyz(i) =  i + myrank
383   END DO
384   CALL subA
385   CALL MPI_Finalize(ierr)
386 END PROGRAM
387
388 SUBROUTINE subA
389   USE shareddata
390   INTEGER :: i
391   DO i = 1, 100
392     xyz(i) = xyz(i) + 1.0
393   END DO
394 END SUBROUTINE
395
396 //C Example
397 #include <mpi.h>
398
399 int myrank;
400 double xyz[100];
401
402 void subA();
403 int main(int argc, char** argv)\{
404   int i;
405   MPI_Init(&argc, &argv);
406   MPI_Comm_rank(MPI_COMM_WORLD, myrank);
407   for(i=0;i<100;i++)
408     xyz[i] = i + myrank;
409   subA();
410   MPI_Finalize();
411 \}
412
413 void subA()\{
414   int i;
415   for(i=0;i<100;i++)
416     xyz[i] = xyz[i] + 1.0;
417 \}
418 \end{alltt}
419
420 \ampi{} executes the main subroutine inside a user-level thread as a subroutine. 
421  
422 Now we transform this program using the argument passing strategy. We first group the
423 shared data into a user-defined type.
424
425 \begin{alltt}
426 !FORTRAN EXAMPLE
427 MODULE shareddata
428   \emph{TYPE chunk}
429     INTEGER :: myrank
430     DOUBLE PRECISION :: xyz(100)
431   \emph{END TYPE}
432 END MODULE
433
434 //C Example
435 struct shareddata\{
436   int myrank;
437   double xyz[100];
438 \};
439 \end{alltt}
440
441 Now we modify the main subroutine to dynamically allocate this data and change the
442 references to them. Subroutine \texttt{subA} is then modified to take this data
443 as argument. 
444
445 \begin{alltt}
446 !FORTRAN EXAMPLE
447 SUBROUTINE MPI_Main
448   USE shareddata
449   USE AMPI
450   INTEGER :: i, ierr
451   \emph{TYPE(chunk), pointer :: c}
452   CALL MPI_Init(ierr)
453   \emph{ALLOCATE(c)}
454   CALL MPI_Comm_rank(MPI_COMM_WORLD, c\%myrank, ierr)
455   DO i = 1, 100
456     \emph{c\%xyz(i) =  i + c\%myrank}
457   END DO
458   CALL subA(c)
459   CALL MPI_Finalize(ierr)
460 END SUBROUTINE
461
462 SUBROUTINE subA(c)
463   USE shareddata
464   \emph{TYPE(chunk) :: c}
465   INTEGER :: i
466   DO i = 1, 100
467     \emph{c\%xyz(i) = c\%xyz(i) + 1.0}
468   END DO
469 END SUBROUTINE
470
471 //C Example
472 void MPI_Main\{
473   int i,ierr;
474   struct shareddata *c;
475   ierr = MPI_Init();
476   c = (struct shareddata*)malloc(sizeof(struct shareddata));
477   ierr = MPI_Comm_rank(MPI_COMM_WORLD, c.myrank);
478   for(i=0;i<100;i++)
479     c.xyz[i] = i + c.myrank;
480   subA(c);
481   ierr = MPI_Finalize();
482 \}
483
484 void subA(struct shareddata *c)\{
485   int i;
486   for(i=0;i<100;i++)
487     c.xyz[i] = c.xyz[i] + 1.0;
488 \}
489 \end{alltt}
490
491 With these changes, the above program can be made thread-safe. Note that it is
492 not really necessary to dynamically allocate \texttt{chunk}. One could have
493 declared it as a local variable in subroutine \texttt{MPI\_Main}.  (Or for a
494 small example such as this, one could have just removed the \texttt{shareddata}
495 module, and instead declared both variables \texttt{xyz} and \texttt{myrank} as
496 local variables). This is indeed a good idea if shared data are small in size.
497 For large shared data, it would be better to do heap allocation because in
498 \ampi{}, the stack sizes are fixed at the beginning (can be specified from the
499 command line) and stacks do not grow dynamically.
500
501 \subsubsection{Source-to-source Transformation}
502 Another approach is to do the changes described in the previous 
503 scheme automatically. It means that we can use a tool to transform 
504 the source code to move global or static variables in an object and pass them around.
505 This approach is portable across systems and compilers and may also 
506 improve locality and hence cache utilization. It also does not have the 
507 context-switch overhead of swapping globals. However, it requires a new 
508 implementation of the tool for each language. Currently, there is a tool called \emph{Photran}\footnote{http://www.eclipse.org/photran}
509 for refactoring Fortran codes that can do this transformation. It is Eclipse-based and works by 
510 constructing Abstract Syntax Trees (ASTs) of the program.
511
512 \subsubsection{Thread Local Store}
513 Thread Local Store (TLS) was originally employed in kernel threads to localize variables and thread safety.
514 It can be used by annotating global/static variables with \emph{\_\_thread} in the source code.
515 It handles both global and static variables and has no context-switching overhead. However, although it is popular, it  
516 is not supported by all compilers. Currently, \charmpp{} supports it for x86/x86\_64 platforms. 
517 A modified \emph{gfortran} is also available to use this feature.
518
519 \subsection{Extensions for Migrations}
520
521 For MPI chunks to migrate, we have added a few calls to \ampi{}. These include
522 ability to register thread-specific data with the run-time system, to pack all
523 the thread's data, and to express willingness to migrate.
524
525 \subsubsection{Registering Chunk data}
526
527 When the \ampi{} runtime system decides that load imbalance exists within the
528 application, it will invoke one of its internal load balancing strategies,
529 which determines the new mapping of \ampi{} chunks so as to balance the load.
530 Then \ampi{} runtime has to pack up the chunk's state and move it to its new
531 home processor. \ampi{} packs up any internal data in use by the chunk,
532 including the thread's stack in use. This means that the local variables
533 declared in subroutines in a chunk, which are created on stack, are
534 automatically packed up by the \ampi{} runtime system. However, it has no way
535 of knowing what other data are in use by the chunk. Thus upon starting
536 execution, a chunk needs to notify the system about the data that it is going
537 to use (apart from local variables.) Even with the data registration, \ampi{}
538 cannot determine what size the data is, or whether the registered data contains
539 pointers to other places in memory. For this purpose, a packing subroutine also
540 needs to be provided to the \ampi{} runtime system along with registered data.
541 (See next section for writing packing subroutines.) The call provided by
542 \ampi{} for doing this is \texttt{MPI\_Register}. This function takes two
543 arguments: A data item to be transported alongwith the chunk, and the pack
544 subroutine, and returns an integer denoting the registration identifier. In
545 C/\CC{} programs, it may be necessary to use this return value after migration
546 completes and control returns to the chunk, using function
547 \texttt{MPI\_Get\_userdata}. Therefore, the return value should be stored in a
548 local variable.
549
550 \subsubsection{Migration}
551
552 The \ampi{} runtime system could detect load imbalance by itself and invoke the
553 load balancing strategy. However, since the application code is going to
554 pack/unpack the chunk's data, writing the pack subroutine will be complicated
555 if migrations occur at a stage unknown to the application. For example, if the
556 system decides to migrate a chunk while it is in initialization stage (say,
557 reading input files), application code will have to keep track of how much data
558 it has read, what files are open etc. Typically, since initialization occurs
559 only once in the beginning, load imbalance at that stage would not matter much.
560 Therefore, we want the demand to perform load balance check to be initiated by
561 the application.
562
563 \ampi{} provides a subroutine \texttt{MPI\_Migrate} for this purpose. Each
564 chunk periodically calls \texttt{MPI\_Migrate}. Typical CSE applications are
565 iterative and perform multiple time-steps. One should call
566 \texttt{MPI\_Migrate} in each chunk at the end of some fixed number of
567 timesteps. The frequency of \texttt{MPI\_Migrate} should be determined by a
568 tradeoff between conflicting factors such as the load balancing overhead, and
569 performance degradation caused by load imbalance. In some other applications,
570 where application suspects that load imbalance may have occurred, as in the
571 case of adaptive mesh refinement; it would be more effective if it performs a
572 couple of timesteps before telling the system to re-map chunks. This will give
573 the \ampi{} runtime system some time to collect the new load and communication
574 statistics upon which it bases its migration decisions. Note that
575 \texttt{MPI\_Migrate} does NOT tell the system to migrate the chunk, but
576 merely tells the system to check the load balance after all the chunks call
577 \texttt{MPI\_Migrate}. To migrate the chunk or not is decided only by the
578 system's load balancing strategy.
579
580 \subsubsection{Packing/Unpacking Thread Data}
581
582 Once the \ampi{} runtime system decides which chunks to send to which
583 processors, it calls the specified pack subroutine for that chunk, with the
584 chunk-specific data that was registered with the system using
585 \texttt{MPI\_Register}. This section explains how a subroutine should be
586 written for performing pack/unpack.
587
588 There are three steps for transporting the chunk's data to other processor.
589 First, the system calls a subroutine to get the size of the buffer required to
590 pack the chunk's data. This is called the ``sizing'' step. In the next step,
591 which is called immediately afterward on the source processor, the system
592 allocates the required buffer and calls the subroutine to pack the chunk's data
593 into that buffer. This is called the ``packing'' step. This packed data is then
594 sent as a message to the destination processor, where first a chunk is created
595 (along with the thread) and a subroutine is called to unpack the chunk's data
596 from the buffer. This is called the ``unpacking'' step.
597
598 Though the above description mentions three subroutines called by the \ampi{}
599 runtime system, it is possible to actually write a single subroutine that will
600 perform all the three tasks. This is achieved using something we call a
601 ``pupper''. A pupper is an external subroutine that is passed to the chunk's
602 pack-unpack-sizing subroutine, and this subroutine, when called in different
603 phases performs different tasks. An example will make this clear:
604
605 Suppose the chunk data is defined as a user-defined type in Fortran 90:
606
607 \begin{alltt}
608 !FORTRAN EXAMPLE
609 MODULE chunkmod
610   TYPE, PUBLIC :: chunk
611       INTEGER , parameter :: nx=4, ny=4, tchunks=16
612       REAL(KIND=8) t(22,22)
613       INTEGER xidx, yidx
614       REAL(KIND=8), dimension(400):: bxm, bxp, bym, byp
615   END TYPE chunk
616 END MODULE
617
618 //C Example
619 struct chunk\{
620   double t;
621   int xidx, yidx;
622   double bxm,bxp,bym,byp;
623 \};
624 \end{alltt}
625
626 Then the pack-unpack subroutine \texttt{chunkpup} for this chunk module is
627 written as:
628
629 \begin{alltt}
630 !FORTRAN EXAMPLE
631 SUBROUTINE chunkpup(p, c)
632   USE pupmod
633   USE chunkmod
634   IMPLICIT NONE
635   INTEGER :: p
636   TYPE(chunk) :: c
637
638   call pup(p, c\%t)
639   call pup(p, c\%xidx)
640   call pup(p, c\%yidx)
641   call pup(p, c\%bxm)
642   call pup(p, c\%bxp)
643   call pup(p, c\%bym)
644   call pup(p, c\%byp)
645 end subroutine
646
647 //C Example
648 void chunkpup(pup_er p, struct chunk c)\{
649   pup_double(p,c.t);
650   pup_int(p,c.xidx);
651   pup_int(p,c.yidx);
652   pup_double(p,c.bxm);
653   pup_double(p,c.bxp);
654   pup_double(p,c.bym);
655   pup_double(p,c.byp);
656 \}
657 \end{alltt}
658
659 There are several things to note in this example. First, the same subroutine
660 \texttt{pup} (declared in module \texttt{pupmod}) is called to size/pack/unpack
661 any type of data. This is possible because of procedure overloading possible in
662 Fortran 90. Second is the integer argument \texttt{p}. It is this argument that
663 specifies whether this invocation of subroutine \texttt{chunkpup} is sizing,
664 packing or unpacking. Third, the integer parameters declared in the type
665 \texttt{chunk} need not be packed or unpacked since they are guaranteed to be
666 constants and thus available on any processor.
667
668 A few other functions are provided in module \texttt{pupmod}. These functions
669 provide more control over the packing/unpacking process. Suppose one modifies
670 the \texttt{chunk} type to include allocatable data or pointers that are
671 allocated dynamically at runtime. In this case, when the chunk is packed, these
672 allocated data structures should be deallocated after copying them to buffers,
673 and when the chunk is unpacked, these data structures should be allocated
674 before copying them from the buffers.  For this purpose, one needs to know
675 whether the invocation of \texttt{chunkpup} is a packing one or unpacking one.
676 For this purpose, the \texttt{pupmod} module provides functions
677 \verb+fpup_isdeleting+(\verb+fpup_isunpacking+). These functions return logical value
678 \verb+.TRUE.+ if the invocation is for packing (unpacking), and \verb+.FALSE.+
679 otherwise. Following example demonstrates this:
680
681 Suppose the type \texttt{dchunk} is declared as:
682
683 \begin{alltt}
684 !FORTRAN EXAMPLE
685 MODULE dchunkmod
686   TYPE, PUBLIC :: dchunk
687       INTEGER :: asize
688       REAL(KIND=8), pointer :: xarr(:), yarr(:)
689   END TYPE dchunk
690 END MODULE
691
692 //C Example
693 struct dchunk\{
694   int asize;
695   double* xarr, *yarr;
696 \};
697 \end{alltt}
698
699 Then the pack-unpack subroutine is written as:
700
701 \begin{alltt}
702 !FORTRAN EXAMPLE
703 SUBROUTINE dchunkpup(p, c)
704   USE pupmod
705   USE dchunkmod
706   IMPLICIT NONE
707   INTEGER :: p
708   TYPE(dchunk) :: c
709
710   pup(p, c\%asize)
711   \emph{
712   IF (fpup_isunpacking(p)) THEN       !! if invocation is for unpacking
713     allocate(c\%xarr(asize))
714     ALLOCATE(c\%yarr(asize))
715   ENDIF
716   }
717   pup(p, c\%xarr)
718   pup(p, c\%yarr)
719   \emph{
720   IF (fpup_isdeleting(p)) THEN        !! if invocation is for packing
721     DEALLOCATE(c\%xarr(asize))
722     DEALLOCATE(c\%yarr(asize))
723   ENDIF
724   }
725
726 END SUBROUTINE
727
728 //C Example
729 void dchunkpup(pup_er p, struct dchunk c)\{
730   pup_int(p,c.asize);
731   if(pup_isUnpacking(p))\{
732     c.xarr = (double *)malloc(sizeof(double)*c.asize);
733     c.yarr = (double *)malloc(sizeof(double)*c.asize);
734   \}
735   pup_doubles(p,c.xarr,c.asize);
736   pup_doubles(p,c.yarr,c.asize);
737   if(pup_isPacking(p))\{
738     free(c.xarr);
739     free(c.yarr);
740   \}
741 \}
742 \end{alltt}
743
744 One more function \verb+fpup_issizing+ is also available in module \texttt{pupmod}
745 that returns \verb+.TRUE.+ when the invocation is a sizing one. In practice one
746 almost never needs to use it.
747
748 \subsection{Extensions for Checkpointing}
749
750 The pack-unpack subroutines written for migrations make sure that the current
751 state of the program is correctly packed (serialized) so that it can be
752 restarted on a different processor. Using the \emph{same} subroutines, it
753 is also possible to save the state of the program to disk, so that if the 
754 program were to crash abruptly, or if the allocated time for the program
755 expires before completing execution, the program can be restarted from the
756 previously checkpointed state. Thus, the pack-unpack subroutines act as the 
757 key facility for checkpointing in addition to their usual role for migration.
758
759 A subroutine for checkpoint purpose has been added to AMPI:
760 \texttt{void MPI\_Checkpoint(char *dirname);}
761 This subroutine takes a directory name as its argument. It is a collective 
762 function, meaning every virtual processor in the program needs to call this 
763 subroutine and specify the same directory name. (Typically, in an
764 iterative AMPI program, the iteration number, converted to a character string,
765 can serve as a checkpoint directory name.) This directory is created, and the
766 entire state of the program is checkpointed to this directory.  One can restart
767 the program from the checkpointed state by specifying \texttt{"+restart
768 dirname"} on the command-line. This capability is powered by the \charmpp{} 
769 runtime system. For more information about \charmpp{} checkpoint/restart
770 mechanism please refer to \charmpp{} manual. 
771
772 \subsection{Extensions for Memory Efficiency}
773
774 MPI functions usually require the user to preallocate the data buffers needed before the
775 functions being called. For unblocking communication primitives, sometimes the user would
776 like to do lazy memory allocation until the data actually arrives, which gives the
777 oppotunities to write more memory efficient programs.     
778 We provide a set of AMPI functions as an extension to the standard MPI-2 one-sided calls,
779 where we provide a split phase MPI\_Get called MPI\_IGet. MPI\_IGet preserves the similar
780 semantics as MPI\_Get except that no user buffer is provided to hold incoming data.
781 MPI\_IGet\_Wait will block until the requested data arrives and runtime system takes
782 care to allocate space, do appropriate unpacking based on data type, and return.
783 MPI\_IGet\_Free lets the runtime system free the resources being used for this get request
784 including the data buffer. And MPI\_IGet\_Data is the utility program that returns the
785 actual data.     
786  
787
788 \begin{alltt}
789
790 int MPI_IGet(MPI_Aint orgdisp, int orgcnt, MPI_Datatype orgtype, int rank,
791              MPI_Aint targdisp, int targcnt, MPI_Datatype targtype, MPI_Win win,
792              MPI_Request *request);
793
794 int MPI_IGet_Wait(MPI_Request *request, MPI_Status *status, MPI_Win win);
795
796 int MPI_IGet_Free(MPI_Request *request, MPI_Status *status, MPI_Win win);
797
798 char* MPI_IGet_Data(MPI_Status status);
799
800 \end{alltt}
801
802
803
804 \subsection{Extensions for Interoperability}
805
806 Interoperability between different modules is essential for coding coupled
807 simulations.  In this extension to \ampi{}, each MPI application module runs
808 within its own group of user-level threads distributed over the physical
809 parallel machine.  In order to let \ampi{} know which chunks are to be created,
810 and in what order, a top level registration routine needs to be written. A
811 real-world example will make this clear. We have an MPI code for fluids and
812 another MPI code for solids, both with their main programs, then we first
813 transform each individual code to run correctly under \ampi{} as standalone
814 codes. This involves the usual ``chunkification'' transformation so that
815 multiple chunks from the application can run on the same processor without
816 overwriting each other's data. This also involves making the main program into
817 a subroutine and naming it \texttt{MPI\_Main}.
818
819 Thus now, we have two \texttt{MPI\_Main}s, one for the fluids code and one for
820 the solids code. We now make these codes co-exist within the same executable,
821 by first renaming these \texttt{MPI\_Main}s as \texttt{Fluids\_Main} and
822 \texttt{Solids\_Main}\footnote{Currently, we assume that the interface code,
823 which does mapping and interpolation among the boundary values of Fluids and
824 Solids domain, is integrated with one of Fluids and Solids.} writing a
825 subroutine called \texttt{MPI\_Setup}.
826
827 \begin{alltt}
828 !FORTRAN EXAMPLE
829 SUBROUTINE MPI_Setup
830   USE ampi
831   CALL MPI_Register_main(Solids_Main)
832   CALL MPI_Register_main(Fluids_Main)
833 END SUBROUTINE
834
835 //C Example
836 void MPI_Setup()\{
837   MPI_Register_main(Solids_Main);
838   MPI_Register_main(Fluids_Main);
839 \}
840 \end{alltt}
841
842 This subroutine is called from the internal initialization routines of \ampi{}
843 and tells \ampi{} how many number of distinct chunk types (modules) exist, and
844 which orchestrator subroutines they execute.
845
846 The number of chunks to create for each chunk type is specified on the command
847 line when an \ampi{} program is run. Appendix B explains how \ampi{} programs
848 are run, and how to specify the number of chunks (\verb|+vp| option). In the
849 above case, suppose one wants to create 128 chunks of Solids and 64 chunks of
850 Fluids on 32 physical processors, one would specify those with multiple
851 \verb|+vp| options on the command line as:
852
853 \begin{alltt}
854 > charmrun gen1.x +p 32 +vp 128 +vp 64
855 \end{alltt}
856
857 This will ensure that multiple chunk types representing different complete
858 applications can co-exist within the same executable. They can also continue to
859 communicate among their own chunk-types using the same \ampi{} function calls
860 to send and receive with communicator argument as \texttt{MPI\_COMM\_WORLD}.
861 But this would be completely useless if these individual applications cannot
862 communicate with each other, which is essential for building efficient coupled
863 codes.  For this purpose, we have extended the \ampi{} functionality to allow
864 multiple ``\texttt{COMM\_WORLD}s''; one for each application. These \emph{world
865 communicators} form a ``communicator universe'': an array of communicators
866 aptly called \emph{MPI\_COMM\_UNIVERSE}. This array of communicators is 
867 indexed [1 . . . \texttt{MPI\_MAX\_COMM}]. In the current implementation,
868 \texttt{MPI\_MAX\_COMM} is 8, that is, maximum of 8 applications can co-exist
869 within the same executable.
870
871 The order of these \texttt{COMM\_WORLD}s within \texttt{MPI\_COMM\_UNIVERSE}
872 is determined by the order in which individual applications are registered in
873 \texttt{MPI\_Setup}.
874
875 Thus, in the above example, the communicator for the Solids module would be
876 \texttt{MPI\_COMM\_UNIVERSE(1)} and communicator for Fluids module would be
877 \texttt{MPI\_COMM\_UNIVERSE(2)}.
878
879 Now any chunk within one application can communicate with any chunk in the
880 other application using the familiar send or receive \ampi{} calls by
881 specifying the appropriate communicator and the chunk number within that
882 communicator in the call. For example if a Solids chunk number 36 wants to send
883 data to chunk number 47 within the Fluids module, it calls:
884
885 \begin{alltt}
886 !FORTRAN EXAMPLE
887 INTEGER , PARAMETER :: Fluids_Comm = 2
888 CALL MPI_Send(InitialTime, 1, MPI_Double_Precision, tag, 
889               \emph{47, MPI_Comm_Universe(Fluids_Comm)}, ierr)
890
891 //C Example
892 int Fluids_Comm = 2;
893 ierr = MPI_Send(InitialTime, 1, MPI_DOUBLE, tag,
894                 \emph{47, MPI_Comm_Universe(Fluids_Comm)});
895 \end{alltt}
896
897 The Fluids chunk has to issue a corresponding receive call to receive this
898 data:
899
900 \begin{alltt}
901 !FORTRAN EXAMPLE
902 INTEGER , PARAMETER :: Solids_Comm = 1
903 CALL MPI_Recv(InitialTime, 1, MPI_Double_Precision, tag, 
904               \emph{36, MPI_Comm_Universe(Solids_Comm)}, stat, ierr)
905
906 //C Example
907 int Solids_Comm = 1;
908 ierr = MPI_Recv(InitialTime, 1, MPI_DOUBLE, tag,
909                 \emph{36, MPI_Comm_Universe(Solids_Comm)}, &stat);
910 \end{alltt}
911
912 \subsection{Extensions for Sequential Re-run of a Parallel Node}
913 In some scenarios, a sequential re-run of a parallel node is desired. One
914 example is instruction-level accurate architecture simulations, in which case
915 the user may wish to repeat the execution of a node in a parallel run in the
916 sequential simulator. AMPI provides support for such needs by logging the change
917 in the MPI environment on a certain processors. To activate the feature, build 
918 AMPI module with variable ``AMPIMSGLOG'' defined, like the following command in
919 charm directory. (Linking with zlib ``-lz'' might be required with this, for
920 generating compressed log file.)
921
922 \begin{alltt}
923 > ./build AMPI net-linux -DAMPIMSGLOG
924 \end{alltt}
925
926 The feature is used in two phases: writing (logging) the environment and
927 repeating the run. The first logging phase is invoked by a parallel run of the
928 AMPI program with some additional command line options. 
929
930 \begin{alltt}
931 > ./charmrun ./pgm +p4 +vp4 +msgLogWrite +msgLogRank 2 +msgLogFilename "msg2.log"
932 \end{alltt}
933
934 In the above example, a parallel run with 4 processors and 4 VPs will be
935 executed, and the changes in the MPI environment of processor 2 (also VP 2,
936 starting from 0) will get logged into diskfile "msg2.log". 
937
938 Unlike the first run, the re-run is a sequential program, so it is not invoked
939 by charmrun (and omitting charmrun options like +p4 and +vp4), and additional
940 comamnd line options are required as well. 
941
942 \begin{alltt}
943 > ./pgm +msgLogRead +msgLogRank 2 +msgLogFilename "msg2.log"
944 \end{alltt}
945
946 \subsection{Communication Optimizations for AMPI}
947 AMPI is powered by the \charmpp{} communication optimization support now!
948 Currently the user needs to specify the communication pattern by command
949 line option. In the future this can be done automatically by the system.
950
951 Currently there are four strategies available: USE\_DIRECT, USE\_MESH,
952 USE\_HYPERCUBE and USE\_GRID. USE\_DIRECT sends the message directly. 
953 USE\_MESH imposes a 2d Mesh virtual topology on the processors so each 
954 processor sends messages to its neighbors in its row and column of the 
955 mesh which forward the messages to their correct destinations. USE\_HYPERCUBE 
956 and USE\_GRID impose a hypercube and a 3d Grid topologies on the processors. 
957 USE\_HYPERCUBE will do best for very small messages and small number of 
958 processors, 3d has better performance for slightly higher message sizes 
959 and then Mesh starts performing best. The programmer is encouraged to try 
960 out all the strategies. (Stolen from the CommLib manual by Sameer :)
961
962 For more details please refer to the CommLib paper \footnote{L. V. Kale and 
963 Sameer Kumar and Krishnan Vardarajan, 2002. 
964 http://finesse.cs.uiuc.edu/papers/CommLib.pdf}. 
965
966 Specifying the strategy is as simple as a command line option +strategy. For
967 example:
968 \begin{alltt}
969 > ./charmrun +p64 alltoall +vp64 1000 100 +strategy USE\_MESH
970 \end{alltt}
971 tells the system to use MESH strategy for CommLib. By default USE\_DIRECT is
972 used.
973
974 \subsection{User Defined Initial Mapping}
975                                                                                 
976 You can define the initial mapping of virtual processors (vp) to physical 
977 processors (p) as a runtime option. You can choose from predefined initial 
978 mappings or define your own mappings. Following predefined mappings are 
979 available:
980                                                                                 
981 \begin{description}
982
983 \item[Round Robin]
984                                                                                 
985 This mapping scheme, maps virtual processor to physical processor in round-robin
986 fashion, i.e. if there are 8 virtual processors and 2 physical processors then
987 virtual processors indexed 0,2,4,6 will be mapped to physical processor 0 and 
988 virtual processors indexed 1,3,5,7 will be mapped to physical processor 1. 
989
990 \begin{alltt}
991 > ./charmrun ./hello +p2 +vp8 +mapping RR\_MAP
992 \end{alltt}
993                                                                                 
994 \item[Block Mapping]
995                                                                                 
996 This mapping scheme, maps virtual processors to physical processor in chunks, 
997 i.e. if there are 8 virtual processors and 2 physical processors then virtual 
998 processors indexed 0,1,2,3 will be mapped to physical processor 0 and virtual 
999 processors indexed 4,5,6,7 will be mapped to physical processor 1.
1000                                                                                 
1001 \begin{alltt}
1002 > ./charmrun ./hello +p2 +vp8 +mapping BLOCK\_MAP
1003 \end{alltt}
1004                                                                                 
1005 \item[Proportional Mapping]
1006                                                                                 
1007 This scheme takes the processing capability of physical processors into account
1008 for mapping virtual processors to physical processors, i.e. if there are 2 
1009 processors with different processing power, then number of virtual processors 
1010 mapped to processors will be in proportion to their processing power.
1011                                                                                 
1012 \begin{alltt}
1013 > ./charmrun ./hello +p2 +vp8 +mapping PROP\_MAP
1014 > ./charmrun ./hello +p2 +vp8
1015 \end{alltt}
1016
1017 \end{description}
1018
1019 If you want to define your own mapping scheme, please contact us for help.
1020
1021 \subsection{Compiling AMPI Programs}
1022
1023 \charmpp{} provides a cross-platform compile-and-link script called \charmc{}
1024 to compile C, \CC{}, Fortran, \charmpp{} and \ampi{} programs.  This script
1025 resides in the \texttt{bin} subdirectory in the \charmpp{} installation
1026 directory. The main purpose of this script is to deal with the differences of
1027 various compiler names and command-line options across various machines on
1028 which \charmpp{} runs. While, \charmc{} handles C and \CC{} compiler
1029 differences most of the time, the support for Fortran 90 is new, and may have
1030 bugs. But \charmpp{} developers are aware of this problem and are working to
1031 fix them. Even in its alpha stage of Fortran 90 support, \charmc{} still
1032 handles many of the compiler differences across many machines, and it is
1033 recommended that \charmc{} be used to compile and linking \ampi{} programs. One
1034 major advantage of using \charmc{} is that one does not have to specify which
1035 libraries are to be linked for ensuring that \CC{} and Fortran 90 codes are
1036 linked correctly together. Appropriate libraries required for linking such
1037 modules together are known to \charmc{} for various machines.
1038
1039 In spite of the platform-neutral syntax of \charmc{}, one may have to specify
1040 some platform-specific options for compiling and building \ampi{} codes.
1041 Fortunately, if \charmc{} does not recognize any particular options on its
1042 command line, it promptly passes it to all the individual compilers and linkers
1043 it invokes to compile the program.
1044
1045 \appendix
1046
1047 \section{Installing AMPI}
1048
1049 \ampi{} is included in the source distribution of \charmpp{}. 
1050 To get the latest sources from PPL, visit:
1051         http://charm.cs.uiuc.edu/
1052
1053 and follow the download link.
1054 Now one has to build \charmpp{} and \ampi{} from source.
1055
1056 The build script for \charmpp{} is called \texttt{build}. The syntax for this
1057 script is:
1058
1059 \begin{alltt}
1060 > build <target> <version> <opts>
1061 \end{alltt}
1062
1063 For building \ampi{} (which also includes building \charmpp{} and other
1064 libraries needed by \ampi{}), specify \verb+<target>+ to be \verb+AMPI+. And
1065 \verb+<opts>+ are command line options passed to the \verb+charmc+ compile
1066 script.  Common compile time options such as \texttt{-g, -O, -Ipath, -Lpath,
1067 -llib} are accepted. 
1068
1069 To build a debugging version of \ampi{}, use the option: ``\texttt{-g}''. 
1070 To build a production version of \ampi{}, use the options: ``\texttt{-O 
1071 -DCMK\_OPTIMIZE=1}''.
1072
1073 \verb+<version>+ depends on the machine, operating system, and the underlying
1074 communication library one wants to use for running \ampi{} programs.
1075 See the charm/README file for details on picking the proper version.
1076 Following is an example of how to build AMPI under linux and ethernet
1077 environment, with debugging info produced:
1078
1079 \begin{alltt}
1080 > build AMPI net-linux -g
1081 \end{alltt}
1082
1083 \section{Building and Running AMPI Programs}
1084 \subsection{Building}
1085 \charmpp{} provides a compiler called charmc in your charm/bin/ directory. 
1086 You can use this compiler to build your AMPI program the same way as other
1087 compilers like cc. Especially, to build an AMPI program, a command line 
1088 option \emph{-language ampi} should be applied. All the command line 
1089 flags that you would use for other compilers can be used with charmc the 
1090 same way. For example:
1091
1092 \begin{alltt}
1093 > charmc -language ampi -c pgm.c -O3
1094 > charmc -language ampi -o pgm pgm.o -lm -O3 
1095 \end{alltt}
1096
1097 Shortcuts to the AMPI compiler are provided. If you have added charm/bin 
1098 into your \$PATH environment variable, simply type \emph{mpicc, mpiCC, 
1099 mpif77,} and \emph{mpif90} as provided by other MPI implementations.
1100
1101 \begin{alltt}
1102 > mpicc -c pgm.c -g
1103 \end{alltt}
1104
1105 \subsection{Running}
1106 \charmpp{} distribution contains a script called \texttt{charmrun} that makes
1107 the job of running \ampi{} programs portable and easier across all parallel
1108 machines supported by \charmpp{}. \texttt{charmrun} is copied to a directory
1109 where an \ampi{} prgram is built using \charmc{}. It takes a command line
1110 parameter specifying number of processors, and the name of the program followed
1111 by \ampi{} options (such as number of chunks to create, and the stack size of
1112 every chunk) and the program arguments. A typical invocation of \ampi{} program
1113 \texttt{pgm} with \texttt{charmrun} is:
1114
1115 \begin{alltt}
1116 > charmrun pgm +p16 +vp32 +tcharm_stacksize 3276800
1117 \end{alltt}
1118
1119 Here, the \ampi{} program \texttt{pgm} is run on 16 physical processors with
1120 32 chunks (which will be mapped 2 per processor initially), where each
1121 user-level thread associated with a chunk has the stack size of 3,276,800 bytes.
1122
1123 \end{document}