Updated and expanded the POSE manual.
authorTerry L. Wilmarth <wilmarth@uiuc.edu>
Thu, 10 Jun 2004 16:08:51 +0000 (16:08 +0000)
committerTerry L. Wilmarth <wilmarth@uiuc.edu>
Thu, 10 Jun 2004 16:08:51 +0000 (16:08 +0000)
doc/pose/Makefile
doc/pose/manual.tex
doc/pose/pplmanual.sty [new file with mode: 0644]
doc/pose/pplmanual.tex [new file with mode: 0644]

index d2dfbbd63a665522560927e15b41be621c55525f..f7d116375926c9bf1643a626759c7443d082e0b6 100644 (file)
@@ -1,9 +1,9 @@
 # Stub makefile for LaTeX PPL manual
 FILE=manual
 TEX=$(FILE).tex 
-
 DEST=pose
 LATEX2HTML=$(L2H) -split 5
+PROJECT_LINK='<a href="http://charm.cs.uiuc.edu/research/pose">POSE Homepage</a><br>'
 
 include ../Makefile.common
 
index 6f14cceb991fceae1b88335f0e6ec9d0babc043b..158d2c2323a7d86c7030da67483d5847d2133d2c 100644 (file)
@@ -1,8 +1,11 @@
 \documentclass[10pt]{article}
-
+\usepackage{fullpage}
+\usepackage{epsf}
 \usepackage{../pplmanual}
 \input{../pplmanual}
 
+\newcommand{\pose}{{\sc Pose}}
+
 \begin{document}
 
 %\maketitle
  \rule{\textwidth}{3pt}
  \vspace{\fill}
  \begin{flushright}
-   \textsf{\Huge POSE User and Reference Manual \\}
+   \textsf{\Huge \pose{} Reference Manual \\}
  \end{flushright}
  \vspace{\fill}
- {\small POSE software and this manual are entirely the fault of Terry
+ {\small \pose{} software and this manual are entirely the fault of Terry
 L. Wilmarth.  Credit for Charm++ is due to the developers, past and
 present, at the Parallel Programming Laboratory ({\tt
-http://charm.cs.uiuc.edu}).  Questions or comments on POSE or this
+http://charm.cs.uiuc.edu}).  Questions or comments on \pose{} or this
 manual can be directed to Terry at {\tt wilmarth@cse.uiuc.edu}.
 } \\
  \rule{\textwidth}{3pt}
@@ -31,27 +34,36 @@ manual can be directed to Terry at {\tt wilmarth@cse.uiuc.edu}.
 \tableofcontents
 \newpage
 
+\section{About this manual}
+
+This manual is {\bf UNDER CONSTRUCTION}.  It is definitely incomplete,
+and probably inaccurate in some cases.  Please e-mail Terry, {\tt
+  wilmarth@uiuc.edu} if you find any problems with the manual.  Thanks.
 
-\section{About POSE}
+\section{About \pose{}}
 
-POSE (Parallel Object-oriented Simulation Environment) is a tool for
-parallel discrete event simulation based on Charm++.  You should have
+\pose{} (Parallel Object-oriented Simulation Environment) is a tool for
+parallel discrete event simulation (PDES) based on Charm++.  You should have
 a background in object-oriented programming (preferably C++), know the
 basic principles behind discrete event simulation, and be familiar
-with the basic syntax of Charm++.  
+with simple parallel programming in Charm++.  
 
-POSE uses the approach of message-driven execution of Charm++, but
-adds the element of discrete timestamps, to control when in simulated
+\pose{} uses the approach of message-driven execution of Charm++, but
+adds the element of discrete timestamps to control when, in simulated
 time, a message is executed.
 
-Users may choose synchronization strategies (conservative or
-optimistic) on a per class basis, depending on the desired behavior of
-the object. 
+Users may choose synchronization strategies (conservative or several
+optimistic variants) on a per class basis, depending on the desired
+behavior of the object.  However, \pose{} is intended to perform best
+with a special type of {\it adaptive} synchronization strategy which
+changes it's be havior on a per object basis.  Thus, other
+synchronization strategies may not be properly maintained.  There are
+two versions of the adaptive strategy, {\sl adapt}, a simple, stable
+version, and {\sl adapt2}, the development version.
 
+\section{Developing a model in \pose{}}
 
-\section{Developing a model in POSE}
-
-Modelling a system in POSE is similar to how you would model in C++ or
+Modelling a system in \pose{} is similar to how you would model in C++ or
 any OOP language.  Objects are entities that hold data, and have a
 fixed set of operations that can be performed on them (methods).
 
@@ -60,777 +72,89 @@ differ dramatically from C++.  The primary difference is that objects
 may exist on a set of processors, and so invoking methods on them
 requires communication via messages. 
 
-POSE adds to Charm++ by putting timestamps on method invocations
+\pose{} adds to Charm++ by putting timestamps on method invocations
 (events), and executing events in timestamp order to preserve the
 validity of the global state.
 
-\begin{figure}[h]
-\begin{center}
-\includegraphics[width=4in]{oopdes}
-\end{center}
-\caption{Object-Method relationship in C++, Charm++ and POSE.}
-\label{fig:oopdes}
-\end{figure}
-
-Thus we can see that developing a model in POSE involves identifying
-the entities we wish to model, determining how they communicate,
-developing a C++ model, accounting for the parallelism of objects by
-creating messages for the Charm++ version, and finally, providing the
-proper event timing info for the system you wish to simulate.
-
-\section{Example: Industrial Process Simulation}
-
-We consider the problem of modelling an industrial process.  
-
-Fiddler's Widgets Inc. is doing a booming business and has decided to
-expand.  They currently have a single automated assembly line and
-would like to add a second.  This addition will involve many
-decisions.  The original assembly line consists of older, less
-efficient, but less expensive equipment.  For the new assembly line,
-they have the option of purchasing new state-of-the-art equipment, or
-the less expensive earlier model.  They would also like to know,
-should they choose to purchase the newer model equipment, would it
-also pay off to replace the older equipment on the original assembly
-line.
-
-The original assembly line consists of:
-
-\begin{enumerate}
-\item A Generator/Dispatcher unit which generates "jobs" (incomplete
-versions of the product made by Fiddler's Widgets) of varying
-complexity at a rate of one per second. 
-\item A Resource/Component Unit which completes the job in a two-phase
-process.  The Resource part of the unit is known to breakdown
-approximately once a week, takes nearly an hour to fix, and greatly
-reduces the number of widgets produced in a 8 hour shift.  In
-addition, approximately 2\% of the widgets produced have errors. The
-Component part of the unit is capable of detecting these errors and
-routing the faulty widget to a junkbin.
-\end{enumerate}
-
-The machine is capable of producing ~656 widgets during an eight-hour
-shift. Each widget earns the company \$4.00 in profit.  The cost of running the
-original assembly line for an eight-hour shift breaks down as follows:
-
-\begin{verbatim}
-COSTS:
-1) Raw material cost:    $ 167.25  ($0.25 per widget)  
-2) Power consumption:    $ 143.97
-3) Employee supervision: $ 640.00  (4 employees @ $20/hr)
-4) Machine maintenance:  $  33.42  ($234.95 over a week)
-   TOTAL:                $ 984.64
-
-PROFIT:
-1) Widgets               $2676.00  (669 widgets @ $4 each)
-
-LOSSES:
-1) Loss to errors:       $  52.00  (2% = approx. 13)
-2) Loss to breakdowns:   $  47.79  (1/7 of profit per hour)
-   TOTAL:                $  99.79
-
-NET: $2676.00 - $984.64 - $99.79 = $1591.57
-
-PURCHASE COSTS:
-Generator/Dispatcher: $ 999
-Resource/Component:   $2150
-\end{verbatim}
-
-
-\begin{figure}[ht]
-\begin{center}
-\includegraphics[width=1in]{oldsys}
-\hskip1in
-\includegraphics[width=2in]{newsys}\\
-\end{center}
-\hskip1.7in(a)\hskip2.2in(b)\\
-\caption{(a) Model of original industrial process system; (b) Model of
-new proposed system.}
-\label{fig:ipsys}
-\end{figure}
-
-The new system consists of:
-
-\begin{enumerate}
-\item A Generator unit that generates jobs in much the
-same way as the original.  It passes the job to:
-\item A Dispatcher unit, which dispatches the jobs to one or more
-Resource units.  The Dispatcher also handles requests from idle
-Resource units for more jobs.  
-\item The Resource units perform phase 1 of the process and can then
-check to see if the job has errors.  The job is thus either discarded
-at this point, or passed on to a single Component unit.
-\item The Component unit performs the second phase of the process to
-complete the job and create the resulting widget.
-\end{enumerate}
-
-The new system improves upon the old in many ways.  The new machines are more
-energy efficient -- a system consisting of one of each unit type uses less
-power than the old system.  Adding more Resource units increases the power
-usage of course.  The new machine also allows for several jobs to be
-undergoing phase 1 -- the long phase simultaneously, in addition to pipelining
-phase 1 and phase 2.  Further, it eliminates the processing of junk jobs in
-phase 2 by detecting them immediately after phase 1.  In addition, maintenance
-costs are lower, and breakdowns are predicted to occur on a resource once per
-20000 jobs processed, with a breakdown time of three hours.  
-
-It does however require more supervision: 2 workers are need to
-operate the Component unit, and one for each other type of unit. Old
-and new units still take the same time to process jobs: a random value
-between 1 and 10 times the job complexity for the first phase and a
-random value between 1 and 3 times the job complexity for the second
-phase. And finally, the new system is much more expensive to purchase.
-
-\begin{verbatim}
-PURCHASE COSTS:
-Generator:  $1500 
-Dispatcher: $2500
-Resource:   $3750
-Component:  $2795
-
-POWER COSTS per 8 hours operation:
-Generator:  $ 30 
-Dispatcher: $ 30
-Resource:   $ 45
-Component:  $ 15
-\end{verbatim}
-
-Thus, the company board wants to know several things:
-
-\begin{enumerate}
-\item How long does it take for the old system to pay for itself?
-\item And the new?  Want to try this with various numbers of Resource units.
-\item What number of resource units produces the max profit?
-\item What number of resource units pays for itself the fastest?
-\end{enumerate}
-
-Because of the parallelism at phase 1, complex jobs might tie up resources,
-but simpler ones might still pass through and keep the Component unit
-busy. Thus it is hard to predict how much this system will improve over the
-old, and with the addition of Resource units.  Thus we should strive to see
-how to make the idle time of the Component close to zero with the fewest
-resources. 
-
-\subsection{Modelling the Original System}
-
-Although we could compute the performance of the original system from
-the available data, it would help us get started if we just simulate
-the original system.  We can compare our results to what is actually
-happening to verify its correctness.
-
-There are exactly 2 entities in the old system, the Generator/Dispatcher and
-the Resource/Component.  To simulate this, we must create a POSE module (we'll
-call this one the 'oldsys'), consisting of a .ci, a .h and a .C file.  These
-files differ in syntax slightly from the equivalent Charm++ code files.
-
-\subsubsection{The Interface File}
-
-A POSE module is made up of a Charm++ Interface file ({\tt .ci}), a
-header file ({\tt .h}) containing message and class declarations, and
-an implementation file ({\tt .C}).  Here's the interface for the old
-system, {\tt oldsys.ci}:
-
-\begin{verbatim}
-message Job;
-message Stats;
-
-poser GeneratorDispatcher : sim opt chpt {
-  entry GeneratorDispatcher(eventMsg *);
-  // Event methods
-  entry [event] void receive(Job *);
-};
-
-poser ResourceComponent : sim opt chpt {
-  entry ResourceComponent(eventMsg *);
-  // Event methods
-  entry [event] void receive(Job *);
-  entry [event] void processJob(eventMsg *);
-  // Non-Event Entry methods
-  entry [sync] Stats *getStats(void);
-};
-\end{verbatim}
-
-Note that we do not use the Charm++ module syntax.  We do however declare our
-messages, and then the objects.  Note that simulation objects are called
-'posers' rather than 'chares', and that a poser behaves as a chare for the
-most part.  It is actually implemented as a chare array element, but this
-should be mostly invisible to the user.  
-
-After the colon in the poser declaration, we have three special terms that
-designate the simulation behavior and representation of the object.  The first
-term is for the wrapper behavior.  The wrapper will control all access to the
-object.  Currently, there is only one wrapper class, sim, and all future
-wrapper classes should inherit from sim.  Second, we have the simulation
-strategy.  This determines the simulation behavior of the object.  Currently,
-we have two basic strategies, con (for conservative) and opt (for optimistic)
-which control the synchronization of the incoming timestamped events.  The
-focus of POSE is to eke out performance improvements using the optimistic
-synchronization mechanism, so we'll select opt for this example.  The final
-term designates the state representation for the object, i.e. it provides a
-policy by which the state can be updated, saved and rolled back.  It also
-maintains a special object virtual time (ovt) for each object.  There is a
-basic representation, rep, which only provides the ovt mechanism, and and more
-complex chpt, which allows, for checkpointing and state recovery.  In general,
-we only need rep to accompany the con strategy, but if we are using opt, we
-will need checkpointing and state recovery, so we will use chpt here. 
-
-The constructor should be considered a timestamped event.  In addition, entry
-methods are designated at timestamped events by the 'event' tag.  Events
-*must* pass a message.  If no data is passed, and the method would otherwise
-be void, the message type should be eventMsg *.  This is because we need to
-put a timestamp on messages and the eventMsg type corresponds to a timestamped
-void message. 
-
-\subsubsection{The Header File}
-
-Now we examine the header file for the old system model,
-{\tt oldsys.h}.  First we define the messages we will be using:
-
-\begin{verbatim}
-class Stats : public CMessage_Stats {
- public:
-  int junkJobs, completedJobs, idleTime;
-};
-\end{verbatim}
-
-Stats is an ordinary Charm++ message.  Job, however, is a POSE event message.
-This means that we leave out the \verb|: public CMessage_Job| bit and provide
-operator= and pup methods, and treat Job as if it were derived from eventMsg.
-Note also that Job has a "next" field which will allow us to store these Job
-messages in a queue.
-
-\begin{verbatim}
-class Job {
- public:
-  int complexity, id;
-  Job *next;
-  Job& operator=(const Job& obj) {
-    eventMsg::operator=(obj);
-    complexity = obj.complexity;
-    id = obj.id;
-    return *this;
-  }
-  void pup(PUP::er &p) {
-    eventMsg::pup(p);
-    p(complexity); p(id);
-  }
-};
-\end{verbatim}
-
-Next we define the poser chares:
-
-\begin{verbatim}
-class GeneratorDispatcher {
- public:
-  GeneratorDispatcher() { }
-  GeneratorDispatcher(eventMsg *);
-  ~GeneratorDispatcher() { }
-  void pup(PUP::er &p) {
-    chpt<state_GeneratorDispatcher>::pup(p);
-  }
-  GeneratorDispatcher& operator=(const GeneratorDispatcher& obj) {
-    rep::operator=(obj);
-    return *this;
-  }  
-  // Event methods
-  void receive(Job *);
-  void receive_anti(Job *) { restore(this); }
-  void receive_commit(Job *) { }
-};
-\end{verbatim}
-
-Note that a parameterless contructor, a destructor, a pup, and an
-operator= are all required for a poser.  Also, for each event method,
-a commit method is required.  Further, for each event method of a
-class that uses the optimistic synchronization strategy, an anti
-method is required as well.  After the receive event method is called,
-the \verb|receive_anti| method simply makes use of the checkpointing
-that is happening to restore the state of the object prior to the
-receive call.
-
-Note also the difference in the superclass pup and assignment
-operators.  The class you are defining will actually be a subclass of
-the representation component in POSE.  Since we've chosen a
-checkpointing representation, we use the chpt parent pup to pack up or
-unpack the entire checkpointed state of the object (pups are used for
-migration -- see the Charm++ manual).  The assignment operator
-in POSE is used for actually copying the state of the object during
-checkpointing.  Thus you only copy the immediate state, and not all the
-checkpointed information, so in this case you only need to call the
-assignment of the base class rep, which assures that the ovt is copied
-properly. 
-
-\begin{verbatim}
-class ResourceComponent {
-  int myHandle, junkJobs, completedJobs;
-  int idleTime, idle, idleStart;
-  Job *queue, *tail;
- public:
-  ResourceComponent() { 
-    junkJobs = completedJobs = idleTime = idle = idleStart = 0; 
-  }
-  ResourceComponent(eventMsg *);
-  ~ResourceComponent() { 
-    Job *tmp = queue;
-    while (tmp) {
-      queue = tmp->next;
-      delete(tmp);
-      tmp = queue;
-    }
-  }
-  void pup(PUP::er &p) {
-    Job *tmp;
-    int count, i;
-    chpt<state_ResourceComponent>::pup(p);
-    p(myHandle); p(junkJobs); p(completedJobs); 
-    p(idleTime); p(idle); p(idleStart);
-
-    if (p.isUnpacking()) {
-      p(count);
-      queue = tail = NULL;
-      if (count > 0)
-        tmp = queue = new Job;
-      for (i=0; i<count; i++) {
-        tmp->pup(p);
-        tmp->next = NULL;
-        if (i+1 < count) {
-          tmp->next = new Job;
-          tmp = tmp->next;
-        }
-        if (i+1 == count) tail = tmp;
-      }
-    }
-    else {
-      count = 0;
-      tmp = queue;
-      while (tmp) {
-        count++;
-        tmp = tmp->next;
-      }
-      p(count);
-      tmp = queue;
-      while (tmp) {
-        tmp->pup(p);
-        tmp = tmp->next;
-      }
-    }      
-  }
-  ResourceComponent& operator=(const ResourceComponent& obj) {
-    Job *tmp1, *tmp2;
-    rep::operator=(obj);
-    myHandle = obj.myHandle;
-    junkJobs = obj.junkJobs;
-    completedJobs = obj.completedJobs;
-    idleTime = obj.idleTime;
-    idle = obj.idle;
-    idleStart = obj.idleStart;
-    queue = tail = NULL;
-    tmp1 = obj.queue;
-    if (tmp1) {
-      tmp2 = queue = tail = new Job;
-      tmp2->next = NULL;
-    }
-    while (tmp1) {
-      (*tmp2) = (*tmp1);
-      if (tmp1->next) {
-        tmp2->next = new Job;
-        tmp2 = tmp2->next;
-        tail = tmp2;
-        tmp2->next = NULL;
-      }
-      tmp1 = tmp1->next;
-    }
-    return *this;
-  }  
-  // Event methods
-  void receive(Job *);
-  void receive_anti(Job *) { restore(this); }
-  void receive_commit(Job *) { }
-  void processJob(eventMsg *);
-  void processJob_anti(eventMsg *) { restore(this); }
-  void processJob_commit(eventMsg *) { }
-  // Non-Event Entry methods
-  Stats *getStats();
-};
-\end{verbatim}
-
-Note that non-event entry methods are still possible and work like regular
-entry methods in Charm++.  The above example uses a sync method to send data
-to the main chare at the end of the program.  Note that commit methods are
-typically empty.  The user may wish to use commit methods to perform special
-actions when an event has been committed to (print statistics, debugging, or
-other information), however, the state of the object when an event is
-committed may differ from when the event was actually executed, so this should
-be used with caution, especially where modifications to the state are
-concerned.  
-
-\subsubsection{The Implementation File}
-
-Finally, we look at the Implementation of our POSE module,
-{\tt oldsys.C} and see how a POSE simulation fits together: 
-
-\begin{verbatim}
-GeneratorDispatcher::GeneratorDispatcher(eventMsg *m)
-{
-  init(m);
-  Job *j = new Job;
-  int i;
-
-  delete(m);
-  eventMsg *e = new eventMsg;
-  POSE_create(ResourceComponent(e), 1, 0);
-
-  j->complexity = (lrand48() % 10) + 1;
-  j->id = 0;
-  POSE_invoke(receive(j), GeneratorDispatcher, 0, 0);
-  initComplete();
-}
-\end{verbatim}
-
-Primary constructors for posers must have a call to init with the incoming
-message as parameter.  Constructor messages must be deleted when you are done
-with them.  This does not hold for event methods -- one should NOT delete
-event messages sent to event methods.  After the data fields of the object are
-initialized, initComplete must be called.  This call could go anywhere after
-all initializations are complete, or be placed at the end of the constructor
-for simplicity. 
-
-Inside a POSE module, we can create other posers using the \verb|POSE_create|
-function.  To invoke event methods on an object, we use some form of the
-\verb|POSE_invoke| function.  The other forms this may take are
-\verb|POSE_invoke_at| and
-\verb|POSE_local_invoke|.  
-
-\begin{verbatim}
-void GeneratorDispatcher::receive(Job *j) { Job *newJ1, *newJ2;
-
-  checkpoint(this);
-  update(j->timestamp);
-  if (j->timestamp < 28800 - 1) {
-    newJ1 = new Job;
-    newJ1->complexity = (lrand48() % 10) + 1;
-    newJ1->id = (j->timestamp)+1;
-    POSE_local_invoke(receive(newJ1), 1);
-  }
-  newJ2 = new Job;
-  newJ2->complexity = j->complexity;
-  newJ2->id = j->id;
-  POSE_invoke(receive(newJ2), ResourceComponent, 1, 0);
-}
-\end{verbatim}
-
-In event methods, we must call a few functions before any other activity.  One
-is the update function, which takes the incoming message and adjusts local
-time (ovt) accordingly.  The other function is used only when we are
-checkpointing, and it checkpoints the state of the object before we make any
-changes to it.  Thus is is necessary to call both these functions before any
-state changes are made and before any time elapses in the method. 
-
-\begin{verbatim}
-ResourceComponent::ResourceComponent(eventMsg *m)
-{
-  init(m);
-  myHandle = 1;
-  idle = 1;
-  junkJobs = completedJobs = 0;
-  idleTime = 0;
-  queue = tail = NULL;
-  delete m;
-  initComplete();
-}
-
-void ResourceComponent::receive(Job *j)
-{
-  eventMsg *m1;
-  Job *tmp = new Job;
-
-  checkpoint(this);
-  update(j->timestamp);
-  
-  if (!tail) {
-    tail = queue = tmp;
-    tmp->next = NULL;
-  }
-  else {
-    tail->next = tmp;
-    tmp->next = NULL;
-    tail = tmp;
-  }
-
-  tmp->complexity = j->complexity;
-  tmp->id = j->id;
-  
-  if (idle) {
-    idleTime += ovt - idleStart;
-    idle = 0;
-    m1 = new eventMsg;
-    POSE_local_invoke(processJob(m1), 0);
-  }
-}
-
-void ResourceComponent::processJob(eventMsg *m)
-{
-  Job *j = queue;
-  eventMsg *m1;
-
-  checkpoint(this);
-  update(m->timestamp);
-  if (!queue) {
-    CkPrintf("ERROR: no jobs in queue.\n");
-    return;
-  }
-  queue = queue->next;
-  if (!queue) tail = NULL;
-
-  // Phase 1
-  elapse(((lrand48() % 10) + 1) * j->complexity);
-
-  // Phase 2
-  elapse(((lrand48() % 3) + 1) * j->complexity);
-
-  if (lrand48() % 100 > 97)
-    junkJobs++;
-  else
-    completedJobs++;
-  if (!queue) {
-    idle = 1;
-    idleStart = ovt;
-  }
-  else {
-    m1 = new eventMsg;
-    POSE_local_invoke(processJob(m1), 0);
-  }
-}
-\end{verbatim}
-
-The above method illustrates one of the ways to specify the passage of
-simulation time.  The other way is to specify an offset when invoking events
-on posers.
-
-\begin{verbatim}
-Stats *ResourceComponent::getStats()
-{
-  Stats *m1 = new Stats;
-
-  m1->junkJobs = junkJobs;
-  m1->completedJobs = completedJobs;
-  m1->idleTime = idleTime;
-  return m1;
-}
-\end{verbatim}
-
-Note that each poser has an id associated with it.  In the above example,
-since there are only two objects, it is hardly noticeable, but the
-GeneratorDispatcher has an id of 0, and the ResourceComponent has an id of 1.
-These ids are the means by which we refer to all the posers in a system.
-Their usage should be apparent in the reference section of this manual. 
-
-
-\subsubsection{The Main Program}
-
-How does one make use of a POSE module?  We show how the POSE
-environment is set up in the following code samples, but first, we
-need to discuss how to process the {\tt oldsys} module so it is
-usable by Charm++. To do this, there exists a perl script {\tt
-etrans.pl}.  We pass in the POSE module name and the script translates
-the POSE module into Charm++ code.
-
-\begin{verbatim}
-> etrans.pl oldsys
-[processing info]
->
-\end{verbatim}
-
-This translator will attempt to alert you if you've done something
-obviously wrong with relation to POSE, but it will not pick up Charm++
-or C++ syntax errors.  It will generate three new files: files {\tt
-X[.ci$|$.h$|$.C]} will be translated to {\tt X\_sim[.ci$|$.h$|$.C]}.  These
-new files are what you use to build the executable simulation.
-
-Now let's build a simple main module that starts up a POSE simulation
-on the module {\tt oldsys} and then gathers statistics, prints them
-and exits.
-
-Here's the {\tt pgm.ci} file:
-
-\begin{verbatim}
-mainmodule Pgm {
-  extern module oldsys;
-  readonly CkChareID mainhandle;
-  
-  mainchare main {
-    entry main();
-    entry void wrapUp();
-  };
-};
-\end{verbatim}
-
-This is a simple Charm++ program that includes the {\tt oldsys}
-module.  Now for the {\tt pgm.h} file:
-
-\begin{verbatim}
-#include "Pgm.decl.h"
-
-CkChareID mainhandle;
-
-class main : public Chare {
-public:
-  main(CkArgMsg *m);
-  main(CkMigrateMessage *) {};
-  void wrapUp();
-};
-\end{verbatim}
-
-Nothing new here if you know Charm++.  We desire that the {\tt wrapUp}
-method gets called at the end of the program and requests statistics
-from the ResourceComponent unit and prints them and exits.  We'll see
-how this is done shortly.  Finally, we have the main program, {\tt
-pgm.C}:
-
-\begin{verbatim}
-#include "pgm.h"
-#include "Pgm.def.h"
-#include "pose.h"
-#include "oldsys_sim.h"
-
-main::main(CkArgMsg *m)
-{ 
-  CkGetChareID(&mainhandle);
-  CProxy_main M(mainhandle);
-
-  srand48(42);
-
-  POSE_endtime = 28800;
-  POSE_init();
-  POSE_registerCallBack(CkCallback(CkIndex_main::wrapUp(), M));
-
-  eventMsg *e = new eventMsg;
-  (*(CProxy_GeneratorDispatcher *) & POSE_Objects)[0].insert(e);
-
-  POSE_start();
-}
-
-void main::wrapUp()
-{
-  CkPrintf("And now for something completely different...\n");
-  Stats *results;
-
-  results = (*(CProxy_ResourceComponent *) & POSE_Objects)[1].getStats();
-  CkPrintf("# completed jobs = %d; # junk jobs = %d; idle time = %d\n", 
-          results->completedJobs, results->junkJobs, results->idleTime);  
-  CkExit();
-}
-\end{verbatim}
-
-There are several things of note here. First, we include both {\tt
-pose.h} and {\tt oldsys\_sim.h} here.  Second, we set a variable called
-{\tt POSE\_endtime}.  This variable specifies to POSE what time (in
-simulation time units) to stop at.  For this particular example, our
-time units are seconds, and we want the simulation to run for an
-eight-hour work shift.  If this variable is not set, the simulation
-runs until quiescence is detected.
-
-The next thing we do is initialize the POSE environment.  Fourth, we
-register {\tt wrapUp} as a callback, so that when the simulation is
-completed, we can print out the information we are interested in.  
-
-Next, we create the GeneratorDispatcher (which in turn creates the
-ResourceComponent).  This ugly syntax is currently necessary for
-making calls into POSE from outside of POSE modules.  It will be
-replaced soon with similar calls as used inside a POSE module.  Now
-that the environment is set up, we start the simulation with a call to
-{\tt POSE\_start}.  The {\tt wrapUp} method also contains an ugly
-syntax line, and a replacement for this is also in the works.
-
-\subsection{Modelling the New System}
-
-For the new system, we want to separate the Generator from the
-Dispatcher, and the Resource from the Component, and make the number
-of resources a parameter to the simulation.  The code for this new
-version is available in the appendix.  
-
-One interesting run of this program with a single resource reveals the
-improvement in the new system allowed by the fact that the two phases
-of the Resource and the Component can now be pipelined to overlap.
-This results in many more completed jobs, but note that the Component
-is still idle for over five hours of the eight-hour work day!
-
-\begin{verbatim}
-Resource 1: # junk jobs = 15;        idle time = 36
-Component:  # completed jobs = 936;  idle time = 18501
-\end{verbatim}
-
-Adding more resources reduces this idle time and dramatically improves
-the system output.  Here is the result for four resources:
-
-\begin{verbatim}
-Resource 1: # junk jobs = 22;         idle time = 36
-Resource 2: # junk jobs = 17;         idle time = 141
-Resource 3: # junk jobs = 23;         idle time = 60
-Resource 4: # junk jobs = 19;         idle time = 55
-Component:  # completed jobs = 3702;  idle time = 36
-\end{verbatim}
-
-A final, very interesting thing to note:  because of the randomness
-applied to processing jobs of various complexities, adding more
-resources to this system still improves the number of completed jobs,
-{\it even though the idle time above is only 36 seconds!}  This is
-because less complex jobs filter through the larger system faster.
-These results can be viewed below.  We used eight resources in this
-run.
-
-\begin{verbatim}
-Resource 1: # junk jobs = 24;        idle time = 36
-Resource 2: # junk jobs = 17;        idle time = 14
-Resource 3: # junk jobs = 18;        idle time = 60
-Resource 4: # junk jobs = 25;        idle time = 55
-Resource 5: # junk jobs = 20;        idle time = 38
-Resource 6: # junk jobs = 21;        idle time = 79
-Resource 7: # junk jobs = 15;        idle time = 243
-Resource 8: # junk jobs = 15;        idle time = 74
-Component:  # completed jobs = 7509; idle time = 13
-\end{verbatim}
-
-Thus we see how simulation can illustrate unpredictable behaviors in a
-system.  For more details on the Industrial Process Simulator, see the
-enhanced code for the original system, the code for the new system,
-and an analysis of the results, in the appendix of this manual.
+Developing a model in \pose{} involves identifying the entities we
+wish to model, determining their interactions with other entities and
+determining how they change over time.
+
+\subsection{PDES in \pose{}}
+
+A simulation in \pose{} consists of a set of entities performing
+timestamped events in parallel.  These entities are called {\sl
+posers}.  \pose{} is designed to work with many such entities per
+processor. The more a system can be broken down into its parallel
+components when designing the simulation model, the more potential
+parallelism in the final application.
+
+A poser class is defined with a synchronization strategy associated
+with it.  We encourage the use of the adaptive strategies, as
+mentioned earlier.  Adaptive strategies are optimistic, and will
+potentially execute events out of order, but have rollback and
+cancellation messages as well as checkpointing abilities to deal with
+this behind the scenes.
+
+Execution is driven by events.  An event arrives for a poser and is
+sorted into a queue by timestamp.  The poser has a local time called
+object virtual time (OVT) which represents its progress through the
+simulation.  When an event arrives with a timestamp $t>$OVT, the OVT is
+advanced to $t$.  If the event has timestamp $t<$OVT, it maybe that
+other events with greater timestamps were executed.  If this is the
+case, a rollback will occur.  If not, the event is simply executed
+along with the others in the queue.
+
+Time can also pass on a poser within the course of executing an
+event.  An {\sl elapse} function is used to advance the OVT.  
+
+Currently, \pose{} has no way to specify event dependencies, so if
+they exist, the programmer must handle errors in ordering carefully.
+\pose{} provides a delayed error message print and abort function that
+is only performed if there is no chance of rolling back the dependency
+error. 
+
+\pose{} maintains a global clock, the global virtual time (GVT), that
+represents the progress of the entire simulation.  
 
 \section{Programmer's Reference}
 
-This section details syntax and usage of POSE constructs.  The last
+This section details syntax and usage of \pose{} constructs.  The last
 subsection lists all constructs and their usage in brief.
 
-\subsection{POSE Modules}
+\subsection{\pose{} Modules}
 
-A POSE module is similar to a Charm++ module.  It is comprised of 
+A \pose{} module is similar to a Charm++ module.  It is comprised of
 {\tt .ci}, {\tt .h}, and {\tt .C} files.  Several posers can be
 described in one module, and the module can include regular chares as
 well.  The module is translated into Charm++ before the simulation can
-be compiled.  This translation generates files suffixed {\tt \_sim.ci},
-{\tt \_sim.h}, and {\tt \_sim.C}.  
+be compiled.  This translation is performed by a Perl script called
+{\sl etrans.pl} which is included with \pose{}.  It generates files
+suffixed {\tt \_sim.ci}, {\tt \_sim.h}, and {\tt \_sim.C}.  
 
 \subsection{Event Message and Poser Interface Description}
 
 Messages, be they event messages or otherwise, are described in the
 {\tt .ci} file exactly the way they are in Charm++, with the exception
-that parameter marshalling cannot be used, and thus you must declare
+that parameter marshalling cannot currently be used, and thus you must declare
 them in the {\tt .h} file.  
 
 ~\\
 \noindent{\tt {\bf message} {\it myMessage};}\\
 
 Posers are described similar to chares, with a few exceptions.  First,
-the {\tt poser} keyword is used to denote that the class is a POSE
+the {\tt poser} keyword is used to denote that the class is a \pose{}
 simulation object class.  Second, event methods are tagged with the
 keyword {\tt event} in square brackets. Finally, three components are
 specified which indicate how objects of the poser class are to be
 simulated.  The {\it sim} component controls the wrapper class and
 event queue used by the object (see section ? for more on the internal
 representation of a poser).  The {\it strat} component controls the
-synchronization strategy the object should use ({\it optimistic} or
-{\it conservative}).  The {\it rep} component specifies the global
+synchronization strategy the object should use ({\it i.e. optimistic}
+or {\it conservative}).  The {\it rep} component specifies the global
 state representation, which controls how the global state is kept
-accurate depending on the synchronization strategy being used.
+accurate depending on the synchronization strategy being used ({\it
+i.e. checkpointing}).
 
 ~\\
 \noindent{\tt {\bf poser} {\it mySim} : {\it sim strat rep} \{\\
@@ -840,16 +164,16 @@ accurate depending on the synchronization strategy being used.
 \noindent \};}\\
 
 Note that the constructors and event methods of a poser must take an
-event message as parameter.  If there is no data that needs to be
-passed in to the method, then the parameter should be of type {\tt
-eventMsg *}.  This ensures that the POSE system will be able to
-timestamp the event.
+event message as parameter.  If there is no data (and thereby no
+message defined) that needs to be passed to the method, then the
+parameter should be of type {\tt eventMsg *}.  This ensures that
+\pose{} will be able to timestamp the event.
 
 \subsection{Declaring Event Messages and Posers}
 
-Event messages are declared with no reference to what they might
-inherit from (unlike in Charm++).  In addition, they must have {\tt
-operator=} defined for them.
+Currently, event messages are declared with no reference to what they
+might inherit from (unlike in Charm++).  The translator takes care of
+this. In addition, they must define {\tt operator=}.
 
 ~\\
 \noindent{\tt class {\it myMessage} \{\\
@@ -871,8 +195,8 @@ operator=} must be provided.  The {\tt pup} method should call the
 
 ~\\
 \noindent{\tt class {\it mySim} \{\\
-\indent int anInt; float aFloat; char aString[20];
-\indent public:\\
+\indent int anInt; float aFloat; char aString[20];\\
+~public:\\
 \indent {\it mySim}();\\
 \indent {\it mySim}({\it myMessage} *m);\\
 \indent \verb|~|{\it mySim}();\\
@@ -894,47 +218,45 @@ implementation will be described next.
 
 The void constructor for a poser should be defined however the user
 sees fit.  It could be given an empty body and should still work for
-POSE.  The entry method constructors (those described in the {\tt .ci}
-file should follow the template below:
+\pose{}.  Poser entry constructors (those described in the {\tt .ci}
+file) should follow the template below:
 
 ~\\
 \noindent{\tt {\it mySim}::{\it mySim}({\it myMessage} *m)\\
 \noindent\{\\
-\indent {\bf init}(m);\\
 \indent // initializations from $m$\\
 \indent ...\\
 \indent delete m;\\
 \indent ...\\
-\indent {\bf initComplete}();\\
 \noindent \};}\\
 
-The {\tt init} function adjust the objects OVT to the correct start
-point, while the {\tt initComplete} function allows the object to
-start processing incoming events.  Note that while the incoming
-message m may be deleted here in the constructor, event messages sent
-to event methods should {\bf not} be deleted.
+Note that while the incoming message $m$ may be deleted here in the
+constructor, event messages received on event methods should {\bf not} be
+deleted.  The PDES fossil collection will take care of those.
 
 An event method should have the following form:
 
 ~\\
 \noindent{\tt void {\it mySim}::{\it myEventMethod}(eventMsg *m) \{\\
-\indent {\bf checkpoint}(this);\\
-\indent {\bf update}(m->timestamp);\\
 \indent // body of method \\
 \noindent \};}\\
 
-All event methods should make the call to {\tt update} and pass in the
-timestamp of the incoming message.  This synchronizes the object's OVT
-with the timestamp of the event.  Also, if the object uses
-checkpointing for its global state representation, you will need to
-checkpoint the current state of the object as shown above.
+Again, $m$ is never deleted in the body of the event.  A side effect
+of optimistic synchronization and rollback is that we would like the
+effects of event execution to be dependent only upon the state
+encapsulated in the corresponding poser.  Thus, accessing arbitrary
+states outside of the simulation, such as by calling {\tt rand}, is
+forbidden.  We are planning to fix this problem by adding a {\tt
+  POSE\_rand()} operation which will generate a random number the first
+time the event is executed, and will checkpoint the number for use in
+subsequent re-executions should a rollback occur.
 
 \subsection{Creation of Poser Objects}
 
 Posers are created within a module using the following syntax:
 
 ~\\
-\noindent {\tt int hdl = 13;\\
+\noindent {\tt int hdl = 13;  // handle should be unique\\
 \noindent {\it myMessage} *m = new {\it myMessage};\\
 \noindent m->someData = 34;\\
 \noindent {\bf POSE\_create}({\it mySim}(m), hdl, 0);}\\
@@ -942,7 +264,8 @@ Posers are created within a module using the following syntax:
 This creates a {\tt mySim} object that comes into existence at
 simulation time zero, and can be referred to by the handle 13.  
 
-Creating a poser from outside the module is somewhat more complex:
+Creating a poser from outside the module ({\it i.e.} from {\tt main})
+is somewhat more complex:
 
 ~\\
 \noindent {\tt int hdl = 13;\\
@@ -951,7 +274,7 @@ Creating a poser from outside the module is somewhat more complex:
 \noindent m->{\bf Timestamp}(0);\\
 \noindent (*(CProxy\_{\it mySim} *) \& {\bf POSE\_Objects})[hdl].insert(m);}\\
 
-This is similar to what the module code ultimately gets translated to,
+This is similar to what the module code ultimately gets translated to
 and should be replaced by a macro with similar syntax soon.
 
 \subsection{Event Method Invocations}
@@ -962,7 +285,7 @@ where the event method is being invoked.  In addition, event messages
 sent to an event method should be allocated specifically for an event
 invocation, and cannot be recycled or deleted.
 
-There are three ways to send events within a POSE module.  The first
+There are three ways to send events within a \pose{} module.  The first
 and most commonly used way involves specifying and offset in
 simulation time from the current time.  The syntax follows:
 
@@ -994,6 +317,9 @@ Posers should not use this approach because of the risk of specifying
 an absolute time that is earlier than the current time on the object
 sending the event.  
 
+Using this method, event methods can be injected into the system from
+outside any module, but this is not recommended.
+
 The third approach is useful when an object send events to itself.  It
 is simply a slightly shorter syntax for the same thing as {\tt
 POSE\_invoke}: 
@@ -1002,16 +328,13 @@ POSE\_invoke}:
 \noindent {\tt aMsg = new {\bf eventMsg};\\
 \noindent {\bf POSE\_local\_invoke}({\it myEventMethod}(aMsg), offset);}\\
 
-Event methods can be injected into the system from outside the module,
-but this is not recommended.  
-
 \subsection{Elapsing Simulation Time}
 
 We've seen in the previous section how it is possible to advance
 simulation time by generating events with non-zero offsets of current
 time.  When such events are received on an object, if the object is
-behind, it brings itself in sync with the event by calling the {\tt
-update} function with the incoming event message.  
+behind, it advances its local simulation time (object virtual time or
+OVT) to the timestamp of the event.
 
 It is also possible to elapse time on an object while the object is
 executing an event.  This is accomplished thus:
@@ -1022,27 +345,67 @@ executing an event.  This is accomplished thus:
 The example above would simulate the passage of forty-two time units
 by adding as much to the object's current OVT.
 
-\subsection{Interacting with a POSE Module and the POSE System}
+\subsection{Interacting with a \pose{} Module and the \pose{} System}
+
+\pose{} modules consist of {\tt <$modname$>.ci}, {\tt <$modname$>.h}
+and {\tt <$modname$>.C} files that are translated via {\tt etrans.pl}
+into {\tt <$modname$>\_sim.ci}, {\tt <$modname$>\_sim.h} and {\tt
+<$modname$>\_sim.C} files.  To interface these with a main program
+module, say $Pgm$ in files {\tt pgm.ci}, {\tt pgm.h} and {\tt pgm.C},
+the {\tt pgm.ci} file must declare the \pose{} module as extern in the
+{\tt mainmodule Pgm} block. For example:
+
+~\\
+\noindent{\tt mainmodule Pgm \{\\
+\indent  extern module <$modname$>;\\
+\indent  readonly CkChareID mainhandle;\\
+   \\
+\indent  mainchare main \{\\
+\indent\indent    entry main();\\
+\indent  \};\\
+\noindent \};}\\
 
-{\it Discuss how to interface main program with POSE module; discuss
-initialization of POSE, etc.}
+The {\tt pgm.C} file should include {\tt pose.h} and {\tt<$modname$>\_sim.h}
+along with its own headers, declarations and whatever else it needs.
 
-\subsection{Glossary of POSE-specific Terms}
+Somewhere in the {\tt main} function, {\tt POSE\_init()} should be
+called.  This initializes all of \pose{}'s internal data structures.
+Then, a termination method should be specified.  \pose{} programs can
+be terminated in two ways: with inactivity detection or with an end
+time.  Inactivity detection terminates after a few iterations of the
+GVT determine that no events are being executed and virtual time is
+not advancing.  When an end time is specified, and the GVT passes it,
+the simulation exits.  Both approaches can be used separately or in
+combination:
+
+~\\
+\noindent{\tt POSE\_useID();\\
+\noindent POSE\_useET($t$);}\\
+
+Now \pose{} is ready for posers.  All posers can be created at this
+point, each with a unique handle.  The programmer is responsible for
+choosing and keeping track of the handles created for posers.  Once
+all posers are created, the simulation can be started:
+
+~\\
+\noindent{\tt POSE\_start();}\\
+
+\subsection{Glossary of \pose{}-specific Terms}
 
 \begin{itemize}
 \item {\tt void {\bf POSE\_init}()}\\
-       $\circ$ Initializes various items in POSE; creates the load balancer
+       $\circ$ Initializes various items in \pose{}; creates the load balancer
        if load balancing is turned on; initializes the statistics
        gathering facility if statistics are turned on.\\
        $\circ$ Must be called in user's main program prior to creation of any
-       simulation objects or reference to any other POSE construct.
+       simulation objects or reference to any other \pose{} construct.
 \item {\tt void {\bf POSE\_start}()}\\
        $\circ$ Sets busy wait to default if none specified; starts
        quiescence detection; starts simulation timer.\\
        $\circ$ Must be called in user's main program when simulation
        should start.
 \item {\tt void {\bf POSE\_registerCallBack}(CkCallback cb)}\\
-       $\circ$ Registers callback function with POSE -- when program
+       $\circ$ Registers callback function with \pose{} -- when program
        ends or quiesces, function is called.\\
        $\circ$ CkCallback is created with the index of the callback
        function and a proxy to the object that function is to be
@@ -1067,9 +430,12 @@ initialization of POSE, etc.}
 \item {\tt void {\bf POSE\_busy\_wait}()}\\
        $\circ$ Busywait for time to compute $fib(n)$ where n is either
        1 or set by {\tt POSE\_set\_busy\_wait}.
-\item {\tt {\bf POSE\_endtime}}\\
-       $\circ$ Set this to $n$ and program will terminate when global
-       virtual time (GVT) reaches $n$.
+\item {\tt {\bf POSE\_useET(t)}}\\
+       $\circ$ Set program to terminate when global
+       virtual time (GVT) reaches $t$.
+\item {\tt {\bf POSE\_useID()}}\\
+       $\circ$ Set program to terminate when no events are available
+       in the simulation.
 \item {\tt void {\bf POSE\_create}({\it constructorName}(eventMsg *m), int
 handle, int atTime)}\\
        $\circ$ Creates a poser object given its constructor, an event
@@ -1083,7 +449,7 @@ handle, int atTime)}\\
        $\circ$ Send a {\it methodName} event with message $m$ to an
        object of type {\it className} designated by handle $handle$
        at time specified by $atTime$.\\
-       $\circ$ This can be used by non-poser objects in the POSE
+       $\circ$ This can be used by non-poser objects in the \pose{}
        module to inject events into the system being simulated.  It
        should not be used by a poser object to generate an event.
 \item {\tt void {\bf POSE\_invoke}({\it methodName}(eventMsg *m),
@@ -1098,33 +464,24 @@ handle, int atTime)}\\
        $\circ$ Send a {\it methodName} event with message $m$ to this
        object at current OVT + $timeOffset$.\\
        $\circ$ This is used by poser objects to send events to themselves.
-\item {\tt void {\bf init}(eventMsg *m)}\\
-       $\circ$ Initializes representation-specific data fields (such
-       as OVT and links to other components of the poser).
-\item {\tt void {\bf initComplete}()}\\
-       $\circ$ Tells the POSE system that the object is ready to
-       start processing events.
-\item {\tt void {\bf checkpoint}(rep *t)}\\
-       $\circ$ Checkpoints the current state, according to
-       checkpointing frequency.
-\item {\tt void {\bf restore}(rep *t)}\\
-       $\circ$ Restores the state from checkpointed data.
-\item {\tt void {\bf update}(eventMsg *m)}\\
-       $\circ$ Brings OVT into sync with event timestamp: if OVT <
-       timestamp, OVT is set to timestamp.
-\item {\tt void {\bf CommitPrint}(char *s)}\\
+\item {\tt void {\bf CommitPrintf}(char *s, args...)}\\
        $\circ$ Buffered print statement; prints when event is
-       committed.\\
+       committed (i.e. will not be rolled back).\\
+       $\circ$ Currently, must be called on the wrapper class
+       (parent) to work properly, but a fix for this is in the works.
+\item {\tt void {\bf CommitError}(char *s, args...)}\\
+       $\circ$ Buffered error statement; prints and aborts program
+       when event is committed.\\
        $\circ$ Currently, must be called on the wrapper class
        (parent) to work properly, but a fix for this is in the works.
 \item {\tt void {\bf elapse}(int n)}\\
        $\circ$ Elapse $n$ simulation time units.
 \item {\tt {\bf poser}}\\
        $\circ$ Keyword (used in place of chare) to denote a poser
-       object in the {\tt .ci} file of a POSE module.
+       object in the {\tt .ci} file of a \pose{} module.
 \item {\tt {\bf event}}\\
        $\circ$ Keyword used in square brackets in the {\tt .ci} file
-       of a POSE module to denote that the entry method is an event method.
+       of a \pose{} module to denote that the entry method is an event method.
 \item {\tt {\bf eventMsg}}\\
        $\circ$ Base class for all event messages; provides timestamp,
        priority and many other properties.
@@ -1134,84 +491,89 @@ handle, int atTime)}\\
        $\circ$ Base class of all strategy classes.
 \item {\tt {\bf con}}\\
        $\circ$ Simple conservative strategy class.
-\item {\tt {\bf opt}}\\
-       $\circ$ Simple optimistic strategy class.
+\item {\tt {\bf opt, opt2, opt3, spec, adapt, adapt2}}\\
+       $\circ$ Optimistic strategy classes.
 \item {\tt {\bf rep}}\\
        $\circ$ Base class for all representation classes.
 \item {\tt {\bf chpt}}\\
        $\circ$ Simple checkpointing representation class.
-\item {\tt {\bf ovt}}\\
-       $\circ$ Accessible data field of the {\tt rep} class; denotes
-       the object virtual time (OVT) of the object; avoid using
-       directly, may become private in the future.
+\item {\tt {\bf OVT()}}\\
+       $\circ$ Returns the object virtual time (OVT) of the poser in
+       which it is called
 \end{itemize}
 
-
-\begin{figure}[h]
-\begin{center}
-\includegraphics[width=1.5in]{base_struct}
-\end{center}
-\caption{The user's view of a {\it poser}, or simulation object, in POSE.}
-\label{fig:base_struct}
-\end{figure}
-
-\section{Delving Deeper into POSE}
-
-This section describes some of the internal representations used by
-POSE, and how to write more efficient parallel discrete event
-simulations.  The first part deals with how POSE simulation objects, or
-{\it posers}, are represented in POSE.  It is useful to know a little
-about this internal representation, when deciding what sort of
-sychronization strategy and global state representation to use.  It is
-also essential to know this structure if you want to add new
-strategies and representations.  Even the simulation wrapper class
-(described below) could be subclassed, to modify how the event queue
-gets handled. 
-
-\begin{figure}[h]
-\begin{center}
-\includegraphics[width=2.5in]{pose_struct}
-\hskip0.5in
-\includegraphics[width=2.5in]{opt_struct}
-\end{center}
-\hskip1.7in(a)\hskip2.2in(b)\\
-\caption{(a) Internal representation of a {\it poser}; (b) internal representation of a {\it poser} using optimistic
-synchronization and checkpointing.}
-\label{fig:pose_struct}
-\end{figure}
-
-\subsection{Structure}
-
-The user of POSE expresses a simulation object that looks very similar
-to a C++ or Charm++ object.  This poser has data fields that make up a
-part of the simulations global state, and events, which look nearly
-identical to Charm++ entry methods.  Further, it can have ordinary
-Charm++ entry methods, as well as its own internal helper functions.  
-
-POSE provides a translator which translates posers into a represention
-that controls access to the object by catching all incoming events to
-the object, placing them in an event queue, and processing them
-according to some strategy.
-
-This internal representation varies based on what synchronization
-strategy and global state representation has been selected.  For
-example, if an optimistic synchronization strategy is used along with a
-checkpointing representation, the internal structure would look like
-that in Fig. ?(b).
-
-\subsection{Load Balancing}
-
-\subsection{Hierarchical Simulations}
-
-\subsection{Continuously Changing Simulation Objects with Discrete
-Behavior Changes}
-
-\appendix
-
-\section{Enhanced {\tt oldsys} Module}
-
-\section{The {\tt newsys} Module}
-
-\section{Industrial Process Simulation Output and Answers to Questions} 
-
-\end{document}
\ No newline at end of file
+\section{Compiling and Running a Sample \pose{} Program}
+
+Sample code is available in the Charm++ source distribution.  Assuming a
+net-linux build of Charm++, look in {\tt charm/net-linux/pgms/pose}.
+The ASIM directory contains a synthetic benchmark simulation and is
+fairly straightforward to understand.
+
+To build a \pose{} simulation, run {etrans.pl} on each \pose{} module
+to get the new source files.  Then build the new source files along with the
+main program and any other source needed with {\tt charmc}, linking
+with {\tt -lpose} and {\tt -language charm++}.  The ASIM example has a
+Makefile that shows this process.
+
+\section{Configuring \pose{}}
+
+\section{Communication Optimizations}
+
+\section{Load Balancing}
+
+\section{Planned Modifications to \pose{} Program Structure, Building Methods and Syntax}
+
+%\begin{figure}[h]
+%\begin{center}
+%\includegraphics[width=1.5in]{fig/base_struct}
+%\end{center}
+%\caption{The user's view of a {\it poser}, or simulation object, in \pose{}.}
+%\label{fig:base_struct}
+%\end{figure}
+%
+%\section{Delving Deeper into \pose{}}
+%
+%This section describes some of the internal representations used by
+%\pose{}, and how to write more efficient parallel discrete event
+%simulations.  The first part deals with how \pose{} simulation objects, or
+%{\it posers}, are represented in \pose{}.  It is useful to know a little
+%about this internal representation, when deciding what sort of
+%sychronization strategy and global state representation to use.  It is
+%also essential to know this structure if you want to add new
+%strategies and representations.  Even the simulation wrapper class
+%(described below) could be subclassed, to modify how the event queue
+%gets handled. 
+%
+%\begin{figure}[h]
+%\centering
+%\includegraphics[width=2.5in]{fig/pose_struct}
+%\hskip0.5in
+%\includegraphics[width=2.5in]{fig/opt_struct}
+%\hskip1.7in(a)\hskip2.2in(b)\\
+%\caption{(a) Internal representation of a {\it poser}; (b) internal representation of a {\it poser} using optimistic
+%synchronization and checkpointing.}
+%\label{fig:pose_struct}
+%\end{figure}
+%
+%\subsection{Structure}
+%
+%The user of \pose{} expresses a simulation object that looks very similar
+%to a C++ or Charm++ object.  This poser has data fields that make up a
+%part of the simulations global state, and events, which look nearly
+%identical to Charm++ entry methods.  Further, it can have ordinary
+%Charm++ entry methods, as well as its own internal helper functions.  
+%
+%\pose{} provides a translator which translates posers into a represention
+%that controls access to the object by catching all incoming events to
+%the object, placing them in an event queue, and processing them
+%according to some strategy.
+%
+%This internal representation varies based on what synchronization
+%strategy and global state representation has been selected.  For
+%example, if an optimistic synchronization strategy is used along with a
+%checkpointing representation, the internal structure would look like
+%that in Fig. ?(b).
+
+%%\subsection{Continuously Changing Simulation Objects with Discrete Behavior Changes}
+
+\end{document}
diff --git a/doc/pose/pplmanual.sty b/doc/pose/pplmanual.sty
new file mode 100644 (file)
index 0000000..f8c0a2c
--- /dev/null
@@ -0,0 +1,243 @@
+\NeedsTeXFormat{LaTeX2e}
+\typeout{^^J^^J
+Parallel Programming Laboratory^^J
+Manual Style^^J
+Written by Milind A. Bhandarkar, 12/00^^J}
+
+%%% Make it possible for both ps and pdf to be generated
+\newif\ifpdf
+\ifx\pdfoutput\undefined
+  \pdffalse
+\else
+  \pdfoutput=1
+  \pdftrue
+\fi
+
+\ifpdf
+  \pdfcompresslevel=9
+\fi
+
+%%% Imported from fullpage.sty, since it is not always available
+\topmargin 0pt
+\advance \topmargin by -\headheight
+\advance \topmargin by -\headsep
+
+\textheight 8.9in
+
+\oddsidemargin 0pt
+\evensidemargin \oddsidemargin
+\marginparwidth 1.0in
+
+\textwidth 6.5in
+%%% end import from fullpage
+
+%%% Commands needed for Maketitle
+\newcommand{\@version}{}
+\newcommand{\@credits}{}
+\newcommand{\version}[1]{\renewcommand{\@version}{#1}}
+\newcommand{\credits}[1]{\renewcommand{\@credits}{#1}}
+
+%%% Print the License Page
+\newcommand{\@license}{%
+ \begin{center}
+   {University of Illinois}\\
+   {\charmpp/\converse\ Parallel Programming System Software}\\
+   {Non-Exclusive, Non-Commercial Use License}\\
+ \end{center}
+ \rule{\textwidth}{1pt}
+{\tiny
+Upon execution of this Agreement by the party identified below (``Licensee''),
+The Board of Trustees of the University of Illinois  (``Illinois''), on behalf
+of The Parallel Programming Laboratory (``PPL'') in the Department of Computer
+Science, will provide the \charmpp/\converse\ Parallel Programming System
+software (``\charmpp'') in Binary Code and/or Source Code form (``Software'')
+to Licensee, subject to the following terms and conditions. For purposes of
+this Agreement, Binary Code is the compiled code, which is ready to run on
+Licensee's computer.  Source code consists of a set of files which contain the
+actual program commands that are compiled to form the Binary Code.
+
+\begin{enumerate}
+  \item
+    The Software is intellectual property owned by Illinois, and all right,
+title and interest, including copyright, remain with Illinois.  Illinois
+grants, and Licensee hereby accepts, a restricted, non-exclusive,
+non-transferable license to use the Software for academic, research and
+internal business purposes only, e.g. not for commercial use (see Clause 7
+below), without a fee.
+
+  \item 
+    Licensee may, at its own expense, create and freely distribute
+complimentary works that interoperate with the Software, directing others to
+the PPL server (\texttt{http://charm.cs.uiuc.edu}) to license and obtain the
+Software itself. Licensee may, at its own expense, modify the Software to make
+derivative works.  Except as explicitly provided below, this License shall
+apply to any derivative work as it does to the original Software distributed by
+Illinois.  Any derivative work should be clearly marked and renamed to notify
+users that it is a modified version and not the original Software distributed
+by Illinois.  Licensee agrees to reproduce the copyright notice and other
+proprietary markings on any derivative work and to include in the documentation
+of such work the acknowledgement:
+
+\begin{quote}
+``This software includes code developed by the Parallel Programming Laboratory
+in the Department of Computer Science at the University of Illinois at
+Urbana-Champaign.''
+\end{quote}
+
+Licensee may redistribute without restriction works with up to 1/2 of their
+non-comment source code derived from at most 1/10 of the non-comment source
+code developed by Illinois and contained in the Software, provided that the
+above directions for notice and acknowledgement are observed.  Any other
+distribution of the Software or any derivative work requires a separate license
+with Illinois.  Licensee may contact Illinois (\texttt{kale@cs.uiuc.edu}) to
+negotiate an appropriate license for such distribution.
+
+  \item
+    Except as expressly set forth in this Agreement, THIS SOFTWARE IS PROVIDED
+``AS IS'' AND ILLINOIS MAKES NO REPRESENTATIONS AND EXTENDS NO WARRANTIES OF
+ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OR
+MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, OR THAT THE USE OF THE
+SOFTWARE WILL NOT INFRINGE ANY PATENT, TRADEMARK, OR OTHER RIGHTS.  LICENSEE
+ASSUMES THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THE SOFTWARE
+AND/OR ASSOCIATED MATERIALS.  LICENSEE AGREES THAT UNIVERSITY SHALL NOT BE HELD
+LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES WITH
+RESPECT TO ANY CLAIM BY LICENSEE OR ANY THIRD PARTY ON ACCOUNT OF OR ARISING
+FROM THIS AGREEMENT OR USE OF THE SOFTWARE AND/OR ASSOCIATED MATERIALS.
+
+  \item 
+    Licensee understands the Software is proprietary to Illinois. Licensee
+agrees to take all reasonable steps to insure that the Software is  protected
+and secured from unauthorized disclosure, use, or release and  will treat it
+with at least the same level of care as Licensee would use to  protect and
+secure its own proprietary computer programs and/or information, but using no
+less than a reasonable standard of care.  Licensee agrees to provide the
+Software only to any other person or entity who has registered with Illinois.
+If licensee is not registering as an individual but as an institution or
+corporation each member of the institution or corporation who has access to or
+uses Software must agree to and abide by the terms of this license. If Licensee
+becomes aware of any unauthorized licensing, copying or use of the Software,
+Licensee shall promptly notify Illinois in writing. Licensee expressly agrees
+to use the Software only in the manner and for the specific uses authorized in
+this Agreement.
+
+  \item
+    By using or copying this Software, Licensee agrees to abide by the
+copyright law and all other applicable laws of the U.S. including, but not
+limited to, export control laws and the terms of this license. Illinois  shall
+have the right to terminate this license immediately by written  notice upon
+Licensee's breach of, or non-compliance with, any terms of the license.
+Licensee may be held legally responsible for any  copyright infringement that
+is caused or encouraged by its failure to  abide by the terms of this license.
+Upon termination, Licensee agrees to  destroy all copies of the Software in its
+possession and to verify such  destruction in writing.
+
+  \item
+  The user agrees that any reports or published results obtained with  the
+Software will acknowledge its use by the appropriate citation as  follows:
+
+\begin{quote}
+``\charmpp/\converse\ was developed by the Parallel Programming Laboratory in
+the Department of Computer Science at the University of  Illinois at
+Urbana-Champaign.''
+\end{quote}
+
+Any published work which utilizes \charmpp\ shall include the following
+reference:
+
+\begin{quote}
+``L. V. Kale and S. Krishnan. \charmpp: Parallel Programming with Message-Driven
+Objects. In 'Parallel Programming using \CC' (Eds. Gregory V. Wilson and Paul
+Lu), pp 175-213, MIT Press, 1996.''
+\end{quote}
+
+Any published work which utilizes \converse\ shall include the following
+reference:
+
+\begin{quote}
+``L. V. Kale, Milind Bhandarkar, Narain Jagathesan, Sanjeev Krishnan and Joshua
+Yelon. \converse: An Interoperable Framework for Parallel Programming.
+Proceedings of the 10th International Parallel Processing Symposium, pp
+212-217, April 1996.''
+\end{quote}
+
+Electronic documents will include a direct link to the official \charmpp\ page
+at \texttt{http://charm.cs.uiuc.edu/}
+
+  \item
+    Commercial use of the Software, or derivative works based thereon,
+REQUIRES A COMMERCIAL LICENSE.  Should Licensee wish to make commercial use of
+the Software, Licensee will contact Illinois (kale@cs.uiuc.edu) to negotiate an
+appropriate license for such use. Commercial use includes: 
+
+    \begin{enumerate}
+      \item
+       integration of all or part of the Software into a product for sale,
+lease or license by or on behalf of Licensee to third parties, or 
+
+      \item
+       distribution of the Software to third parties that need it to
+commercialize product sold or licensed by or on behalf of Licensee.
+    \end{enumerate}
+
+  \item
+    Government Rights. Because substantial governmental funds have been  used
+in the development of \charmpp/\converse, any possession, use or sublicense of
+the Software by or to the United States government shall be subject to such
+required restrictions.
+
+  \item
+    \charmpp/\converse\ is being distributed as a research and teaching tool
+and as such, PPL encourages contributions from users of the code that might, at
+Illinois' sole discretion, be used or incorporated to make the basic  operating
+framework of the Software a more stable, flexible, and/or useful  product.
+Licensees who contribute their code to become an internal  portion of the
+Software agree that such code may be distributed by  Illinois under the terms
+of this License and may be required to sign an  ``Agreement Regarding
+Contributory Code for \charmpp/\converse\ Software'' before Illinois  can
+accept it (contact \texttt{kale@cs.uiuc.edu} for a copy).
+\end{enumerate}
+
+UNDERSTOOD AND AGREED.
+
+Contact Information:
+
+The best contact path for licensing issues is by e-mail to
+\texttt{kale@cs.uiuc.edu} or send correspondence to:
+
+\begin{quote}
+Prof. L. V. Kale\\
+Dept. of Computer Science\\
+University of Illinois\\
+1304 W. Springfield Ave\\
+Urbana, Illinois 61801 USA\\
+FAX: (217) 333-3501
+\end{quote}
+}%tiny
+ \newpage
+}% end of license
+
+\renewcommand{\maketitle}{\begin{titlepage}%
+ \begin{flushright}
+   {\Large
+     Parallel Programming Laboratory\\
+     University of Illinois at Urbana-Champaign\\
+   }
+ \end{flushright}
+ \rule{\textwidth}{3pt}
+ \vspace{\fill}
+ \begin{flushright}
+   \textsf{\Huge \@title \\}
+ \end{flushright}
+ \vspace{\fill}
+ \@credits \\
+ \rule{\textwidth}{3pt}
+ \begin{flushright}
+   {\large Version \@version}
+ \end{flushright}
+ \end{titlepage}
+ \@license
+
+ \tableofcontents
+ \newpage
+}% maketitle
+
diff --git a/doc/pose/pplmanual.tex b/doc/pose/pplmanual.tex
new file mode 100644 (file)
index 0000000..43cbbf5
--- /dev/null
@@ -0,0 +1,39 @@
+%%% Commonly Needed packages
+\usepackage{graphicx,color,calc}
+\usepackage{makeidx}
+\usepackage{alltt}
+\usepackage[linkbordercolor=(0 0 1),citebordercolor=(0 1 0)]{hyperref}
+\usepackage{xspace}
+
+%%% Commands for uniform looks of C++, Charm++, and Projections
+\newcommand{\CC}{C\hbox{++}}
+\newcommand{\emCC}{C\hbox{\em++}}
+\newcommand{\charmpp}{\textsc{Charm++}}
+\newcommand{\charmc}{\texttt{charmc}}
+\newcommand{\projections}{\textsc{Projections}}
+\newcommand{\converse}{\textsc{Converse}}
+\newcommand{\ampi}{\textsc{AMPI}}
+\newcommand{\tempo}{\textsc{TeMPO}}
+\newcommand{\irecv}{\textsl{iRecv}}
+\newcommand{\sdag}{\textsl{Structured Dagger}}
+\newcommand{\jade}{Jade\xspace}
+
+%%% Commands to produce margin symbols
+\newcommand{\new}{\marginpar{\fbox{\bf$\mathcal{NEW}$}}}
+\newcommand{\important}{\marginpar{\fbox{\bf\Huge !}}}
+\newcommand{\experimental}{\marginpar{\fbox{\bf\Huge $\beta$}}}
+
+%%% Commands for manual elements
+\newcommand{\zap}[1]{ }
+\newcommand{\function}[1]{{\noindent{\textsf{#1}}\\}}
+\newcommand{\cmd}[1]{{\noindent{\textsf{#1}}\\}}
+\newcommand{\args}[1]{\hspace*{2em}{\texttt{#1}}\\}
+\newcommand{\prototype}[1]{\vspace{0.2in}\index{#1}}
+\newcommand{\param}[1]{{\texttt{#1}}}
+\newcommand{\kw}[1]{{\textsf{#1}\index{#1}}}
+\newcommand{\uw}[1]{{\textsl{#1}}}
+\newcommand{\desc}[1]{\indent{#1}}
+\newcommand{\note}[1]{(\textbf{Note:} #1)}
+\newcommand{\term}[1]{{\bf #1}\index{#1}}
+
+\makeindex