Merge branch 'newManual' of charmgit:charm into newManual
authorRamprasad Venkataraman <ramv@illinois.edu>
Tue, 24 Jul 2012 21:56:22 +0000 (16:56 -0500)
committerRamprasad Venkataraman <ramv@illinois.edu>
Tue, 24 Jul 2012 21:56:22 +0000 (16:56 -0500)
doc/charm++/advancedarrays.tex
doc/charm++/arrays.tex
doc/charm++/checkpoint.tex
doc/charm++/loadb.tex
doc/charm++/manual.tex
doc/charm++/pup.tex

index a76766e973e004e69bce48bcf3b77009388a2a2e..25b3bede49a2819183071147656dc9e0900e9fbc 100644 (file)
@@ -376,7 +376,7 @@ created elements.
 
 
 
-\subsubsection{User-defined array index type}
+\subsubsection{User-defined Array Index Type}
 \label{user-defined array index type}
 
 \index{Array index type, user-defined}
index c6d831e8ab7ad03378b341f45956872ce147f52b..8f414da462ae394599d0d78acef336176bb17ec3 100644 (file)
@@ -184,9 +184,11 @@ aF[CkArrayIndexFoo(...)].doAgain(\uw{parameters});
 \end{alltt}
 
 You may invoke methods on array elements that have not yet been created. The
-system will buffer the message until the element is created.\footnote{However,
-  the element must eventually be created (i.e. within a 3-minute buffering
-  period).}
+\charmpp{} runtime system will buffer the message until the element is
+created. 
+%\footnote{However, the element must eventually be created (i.e. within
+%a 3-minute buffering period).}
+\footnote{However, the element must eventually be created.}
 
 Messages are not guarenteed to be delivered in order. For instance, if a method
 is invoked on method \kw{A} and then method \kw{B}; it is possible that \kw{B}
@@ -198,7 +200,7 @@ a1[i].B();
 \end{alltt}
 
 Messages sent to migrating elements will be delivered after the migrating
-element arrives on the destination processor. It is an error to send a message
+element arrives on the destination PE. It is an error to send a message
 to a deleted array element.
 
 \subsection{Broadcasts on Chare Arrays}
index 5ee7c082d8366007130d51514f893af4051f46ce..01ae9805ac9d8f393f6f6171a52f06ac640abff2 100644 (file)
@@ -4,11 +4,10 @@
 \label{sec:checkpoint}
 
 \charmpp{} offers a range of fault tolerance capabilities through its 
-checkpoint/restart mechanism. Usual Chare array-based \charmpp{} application 
-including AMPI application can be checkpointed to disk files and later 
-on restarting from the files.
+checkpoint/restart mechanism. Usual chare-array-based \charmpp{} applications, 
+including AMPI applications, can be checkpointed to disk files and be restarted later from the files.
 
-The basic idea behind this is straightforward: Checkpointing an 
+The basic idea behind this is straightforward: checkpointing an 
 application is like migrating its parallel objects from the processors
 onto disks, and restarting is the reverse. Thanks to the migration 
 utilities like PUP'ing(Section~\ref{sec:pup}), users can decide what 
@@ -44,15 +43,14 @@ Therefore, it is up to the programmer what to save and restore for
 the application. One illustration of this flexbility is a complicated
 scientific computation application with 9 matrices, 8 of which holding 
 the intermediate results and 1 holding the final results of each timestep.
-To save resource, the PUP routine can well omit the 8 intermediate matrices
+To save resources, the PUP routine can well omit the 8 intermediate matrices
 and checkpoint the matrix with final results of each timestep. 
 
 Group and nodegroup objects(Section~\ref{sec:group}) are normally not 
 meant to be migrated. In order to checkpoint them, however, the user 
-wants to write PUP routines for the groups and declare them as 
+has to write PUP routines for the groups and declare them as 
 {\tt [migratable]} in the .ci file. Some programs use {\it mainchares}
-to hold key control data like global object counts, and thus needs
-mainchares be checkpointed too. To do this, the programmer should write
+to hold key control data like global object counts, and thus mainchares need to be checkpointed too. To do this, the programmer should write
 a PUP routine for the mainchare and declare them as {\tt [migratable]} 
 in the .ci file, just as in the case of Group and NodeGroup. In addition,
 the programmer also needs to put the proxy to the mainchare (usually 
@@ -66,44 +64,43 @@ name is created and a collection of checkpoint files are written into it.
 
 The user can choose to run the \charmpp{} application in restart mode, i.e.,
 restarting execution from last checkpoint. The command line option {\tt
--restart DIRNAME} is required to invoke this mode. For example:
++restart DIRNAME} is required to invoke this mode. For example:
 
 \begin{alltt}
   > ./charmrun hello +p4 +restart log
 \end{alltt}
 
 Restarting is the reverse process of checkpointing. \charmpp{} allows 
-restarting the old checkpoint on different number of physical processor.
+restarting the old checkpoint on a different number of physical processors.
 This provides the flexibility to expand or shrink your application when
-the availability of computing resource changes. 
+the availability of computing resources changes. 
 
 Note that on restart, if the old reduction client was set to a static 
 function, the function pointer might be lost and the user needs to register
 it again. A better alternative is to always use entry method of a chare
 object. Since all the entry methods are registered inside \charmpp{} system,
-in restart phase, the reduction client will be automatically restored.
+in the restart phase, the reduction client will be automatically restored.
 
-After a failure, the system may consist less number of processors. After
-a problem fixed, some processors may become available again. Therefore,
-the user may need to flexibility to restart on different number of processors
-than in the checkpointing phase. This is allowable by giving different 
+After a failure, the system may contain less number of processors. Once the failed components have been repaired, some processors may become available again. Therefore,
+the user may need the flexibility to restart on a different number of processors
+than in the checkpointing phase. This is allowable by giving a different 
 {\tt +pN} option at runtime. One thing to note is that the new load 
 distribution might differ from the previous one at checkpoint time,
-so running a load balancing (See Section~\ref{loadbalancing}) is suggested. 
+so running a load balancer (see Section~\ref{loadbalancing}) after restart is suggested. 
 
 If restart is not done on the same number of processors, the processor-specific
 data in a group/nodegroup branch cannot (and usually should not) be 
-restored individually. A copy from processor 0 will be propagate to all 
+restored individually. A copy from processor 0 will be propagated to all 
 the processors.
 
 \subsubsection{Choosing What to Save}
 
 In your programs, you may use chare groups for different types of purposes. 
 For example, groups holding read-only data can avoid excessive data copying,
-while groups maintaining processor-specific information is used as a local
+while groups maintaining processor-specific information are used as a local
 manager of the processor. In the latter situation, the data is sometimes
 too complicated to save and restore but easy to re-compute. For the read-only
-data, you want to save and restore it in the PUP'er routing and leave empty
+data, you want to save and restore it in the PUP'er routine and leave empty
 the migration constructor, via which the new object is created during restart.
 For the easy-to-recompute type of data, we just omit the PUP'er routine and
 do the data reconstruction in the group's migration constructor.
@@ -111,7 +108,7 @@ do the data reconstruction in the group's migration constructor.
 A similar example is the program mentioned above, where there aree two 
 types of chare arrays, one maintaining intermediate results while the 
 other type holding the final result for each timestep. The programmer 
-can take advantage of the flexibility by omitting PUP'er routine empty
+can take advantage of the flexibility by leaving PUP'er routine empty
 for intermediate objects, and do save/restore only for the important 
 objects. 
 
@@ -134,7 +131,7 @@ This double checkpointing ensures the availability of one checkpoint in case
 the other is lost. 
 The double in-memory checkpoint/restart scheme is useful and efficient
 for applications with small memory footprint at the checkpoint state. 
-The double in-disk variation stores checkpoints into local disk, thus 
+The double in-disk variant stores checkpoints into local disk, thus 
 can be useful for applications with large memory footprint. 
 %Its advantage is to reduce the recovery
 %overhead to seconds when a failure occurs.
@@ -143,8 +140,7 @@ can be useful for applications with large memory footprint.
 
 \subsubsection{Checkpointing}
 
-The function that user can call to initiate a checkpointing in a Chare 
-array-based application is: 
+The function that user can call to initiate a checkpointing in a chare-array-based application is: 
 
 \begin{alltt}
       void CkStartMemCheckpoint(CkCallback &cb)
@@ -155,7 +151,7 @@ Just like the above disk checkpoint described, it is up to programmer what to sa
 The programmer is responsible for choosing when to activate checkpointing so that
 the size of a global checkpoint state can be minimal.
 
-In AMPI applications, user just needs to call the following function to 
+In AMPI applications, the user just needs to call the following function to 
 start checkpointing:
 
 \begin{alltt}
@@ -165,28 +161,28 @@ start checkpointing:
 \subsubsection{Restarting}
 
 When a processor crashes, the restart protocol will be automatically
-invoked to recover all objects using the last checkpoints. And then the program
-will continue to run on the survived processors. This is based on the assumption
+invoked to recover all objects using the last checkpoints. The program
+will continue to run on the surviving processors. This is based on the assumption
 that there are no extra processors to replace the crashed ones. 
 
 However, if there are a pool of extra processors to replace the crashed ones, 
-the fault-toerlance protocol can also take advantage of this to grab one
+the fault-tolerance protocol can also take advantage of this to grab one
 free processor and let the program run on the same number of processors 
-as before crash. 
+as before the crash. 
 In order to achieve this, \charmpp{} needs to be compiled with the macro option
  {\it CK\_NO\_PROC\_POOL} turned on.
 
 
 \subsubsection{Double in-disk checkpoint/restart}
 
-A variation of double memory checkpoint/restart,
+A variant of double memory checkpoint/restart,
 {\it double in-disk checkpoint/restart},
-can be applied to applcaitions with large memory footprint.
+can be applied to applications with large memory footprint.
 In this scheme, instead of storing checkpoints in the memory, it stores 
 them in the local disk.
-The checkpoint files are named "ckpt[CkMyPe]-[idx]-XXXXXX" and are stored under /tmp.
+The checkpoint files are named ``ckpt[CkMyPe]-[idx]-XXXXX'' and are stored under the /tmp directory.
 
-A programmer can use runtime option {\it +ftc\_disk} to switch to this mode.
+A programmer should use the runtime option {\it +ftc\_disk} to switch to this mode.
 For example:
 
 \begin{alltt}
index a81c30d006b8fa20a91750fc8fe34185748c7130..87444fc8523e92a0f6794dcd9e257c07c0b01c3d 100644 (file)
@@ -1,45 +1,48 @@
-
 \subsection{Load Balancing}
 
 \label{loadbalancing}
 
 %(This introduction added on 11/12/2003)
 
-Charm++ supports load balancing, enabled by the fact there are a large
-number of chares or chare-array-elements typically available to map to
-existing processors, and that they can be migrated at runtime.
-
-Many parallel applications, especially physical simulations, are
-iterative in nature. They may contain a series of time-steps, and/or
-iterative solvers that run to convergence. For such computations,
-typically, the heuristic principle that we call ``principle of
-persistence'' holds: the computational loads and communication patterns
-between objects (chares) tend to persist over time, even in dynamic
-applications. In such cases, recent past is a good predictor of near
-future. Measurement-based chare migration strategies are useful in
-this context. Currently these apply to chare-array elements, but they
-may be extended to chares in the future.
-
-For applications without such iterative structure, or with iterative structure
-but without the predictability (i.e. where the principle of persistence does
-not apply), Charm++ supports ``seed balancers'' that move seeds for new chares
-among processors (possibly repeatedly) to achieve load balance. These
-strategies are currently available for both chares and chare-arrays.  Seed
-balancers were the original load balancers provided in Charm since the late
-80's. They are extremely useful for state-space search applications, and are
-also useful in other computations, as well as in conjunction with migration
+Load balancing in \charmpp{} is enabled by its ability to place, or
+migrate, chares or chare-array-elements.  Typical application usage to
+exploit this feature will construct many more chares than processors, and
+enable their runtime migration.
+
+Iterative applications, which are commonplace in physical simulations,
+are the most suitable target for \charmpp{}'s measurement based load
+balancing techniques.  Such applications may contain a series of
+time-steps, and/or iterative solvers that run to convergence. For such
+computations, typically, the heuristic principle that we call
+``principle of persistence'' holds: the computational loads and
+communication patterns between objects (chares) tend to persist over
+multiple iterations, even in dynamic applications. In such cases,
+the recent past is a good predictor of the near future. Measurement-based
+chare migration strategies are useful in this context. Currently these
+apply to chare-array elements, but they may be extended to chares in
+the future.
+
+For applications without such iterative structure, or with iterative
+structure, but without predictability (i.e. where the principle of
+persistence does not apply), Charm++ supports ``seed balancers'' that
+move ``seeds'' for new chares among processors (possibly repeatedly)
+to achieve load balance. These strategies are currently available for
+both chares and chare-arrays.  Seed balancers were the original load
+balancers provided in Charm since the late 80's. They are extremely
+useful for state-space search applications, and are also useful in
+other computations, as well as in conjunction with migration
 strategies.
 
-For iterative computations when there is a correlation between iterations/steps
-but either it is not strong or the machine environment is not predictable
-(noise due to OS interrupts on small time steps, or time-shared desktop
+For iterative computations when there is a correlation between iterations/steps,
+but either it is not strong,k or the machine environment is not predictable
+(due to noise from OS interrupts on small time steps, or time-shared desktop
 machines), one can use a combination of the two kinds of strategies. The
 baseline load balancing is provided by migration strategies, but in each
 iteration one also spawns off work in the form of chares that can run on any
 processor. The seed balancer will handle such work as it arises.
 
-Examples are in the directories of {\tt examples/charm++/load\_balancing} and 
-{\tt tests/charm++/load\_balancing}
+Examples are in {\tt examples/charm++/load\_balancing} and {\tt
+  tests/charm++/load\_balancing}
 \subsubsection{Measurement-based Object Migration Strategies}
 
 \label{lbFramework}
index 21297cf5417a908268e09335c49951a47f864a24..ed133936ea6d46955ef8f788a7a2ccbd74444bca 100644 (file)
   \input{entry}
   \input{messages}
   \input{order.tex}
+  \input{callbacks}
   \input{advancedarrays}
   \input{advancedlb}
   \input{futures}
   \input{quiesce}
-  \input{callbacks}
   \input{reductions}
   \input{advancedpup}
   \input{othercalls}    
index d3f43a397270b2bf3bc04e2300070110caba5f7a..63aac0ee4fc440201097d36c4f5eb61f24a15642 100644 (file)
@@ -1,5 +1,3 @@
-\subsection{Serialization using PUP Framework}
-
 \label{sec:pup}
 
 The \index{PUP} PUP framework is a generic way to describe the data in an object and to use that description for any task requiring serialization.
@@ -40,7 +38,7 @@ checkpoint and restart calculations involving \uw{foo}s.
 
 
 
-\subsubsection{PUP contract}
+\subsection{PUP contract}
 
 \label{sec:pupcontract}
 Your object's \uw{pup} method must save and restore all your object's
@@ -59,7 +57,7 @@ pup method is when you don't have a superclass.  If your superclass has
 no pup method, you must pup the values in the superclass yourself.
 
 
-\paragraph{PUP operator}
+\subsubsection{PUP operator}
 \label{sec:pupoperator}
 
 The recommended way to pup any object \verb.a. is to use \verb.p|a;..
@@ -97,13 +95,13 @@ This utility method is defined for user-defined types T as:
     \}
   \end{alltt}
 
-\paragraph{PUP STL Container Objects}
+\subsubsection{PUP STL Container Objects}
 \label{sec:pupstl}
 If the variable is from the C++ Standard Template Library, you can include 
 operator\verb.|.'s for STL vector, map, list, pair, and string, templated
 on anything, by including the header ``pup\_stl.h''.
 
-\paragraph{PUP Dynamic Data}
+\subsubsection{PUP Dynamic Data}
 As usual in \CC{}, pointers and allocatable objects usually require special handling. 
 Typically this only requires a \kw{p.isUnpacking()} conditional block, 
 where you perform the appropriate allocation.  See 
@@ -122,7 +120,7 @@ operator\verb.|. might look like:
 \end{alltt}
 
 
-\paragraph{PUP as bytes}
+\subsubsection{PUP as bytes}
 
 \label{sec:pupbytes}
 
@@ -157,7 +155,7 @@ work across different machine architectures.  This is currently
 an uncommon scenario, but heterogenous architectures may become more
 common, so pupping as bytes is discouraged.
 
-\paragraph{PUP overhead}
+\subsubsection{PUP overhead}
 
 \label{sec:pupoverhead}
 
@@ -170,7 +168,7 @@ with the ``PUPbytes'' declaration, \kw{PUParray} uses an even faster block
 transfer, with one virtual function call per array.
 
 
-\paragraph{PUP structured dagger}
+\subsubsection{PUP structured dagger}
 
 \label{sec:pupsdag}
 
@@ -192,7 +190,7 @@ class bar : public barParent \{
 
 
 
-\paragraph{PUP modes}
+\subsubsection{PUP modes}
 
 \label{sec:pupmodes}
 
@@ -227,8 +225,10 @@ have their destructor called when they are deleted, so the
 \kw{p.isDeleting()} call is not normally required---instead,
 memory should be deallocated in the destructor as usual.
 
+More specialized modes and PUP::ers are described in section~\ref{sec:PUP:CommonPUPers}. 
+
 
-\subsubsection{Life Cycle}
+\subsection{PUP Life Cycle}
 
 \label{sec:lifecycle}
 
@@ -263,9 +263,8 @@ repeatedly over the object lifetime.
 Finally, objects are destroyed by calling their destructor
 as usual.
 
-More specialized modes and PUP::ers are described in section~\ref{sec:PUP:CommonPUPers}. 
 
-\subsubsection{Migratable Array Elements}
+\subsection{Migratable Array Elements using PUP}
 
 \label{arraymigratable}
 Array objects can \index{migrate}migrate from one PE to another.  For
@@ -303,7 +302,7 @@ void A2::pup(PUP::er \&p)
 \}
 \end{alltt}
 
-\subsubsection{Marshalling User Defined Data Types via PUP}
+\subsection{Marshalling User Defined Data Types via PUP}
 
 Parameter marshalling requires serialization and is therefore
 implemented using the PUP framework.  User defined data types passed