Changed to reflect new nomenclature and fix numerous bugs
authorCelso Mendes <cmendes@illinois.edu>
Tue, 21 Nov 2006 06:10:11 +0000 (06:10 +0000)
committerCelso Mendes <cmendes@illinois.edu>
Tue, 21 Nov 2006 06:10:11 +0000 (06:10 +0000)
doc/bigsim/install.tex
doc/bigsim/manual.tex

index b101cfe16cee5db3aec0d13f343ced2b84aba49e..27f8b334284e57680b3bb6ee46f37413687b9706 100644 (file)
@@ -3,46 +3,56 @@
 
 \subsection{Installing Charm++ and BigSim}
 
-BigSim Simulator is distributed as a part of the Charm++ standard distribution.
-One needs to download Charm++ and compile BigSim simulator.
-One should begin with downloading Charm++ from the website:
+% #CLM# BigSim Simulator is distributed as a part of the Charm++ standard distribution.
+    The BigSim Simulator is distributed as part of the Charm++ standard distribution.
+One needs to download Charm++ and compile the BigSim Simulator.
+% #CLM# One should begin with downloading Charm++ from the website:
+This process should begin with downloading Charm++ from the website:
 http://charm.cs.uiuc.edu.
 
-Please refer to ``Charm++ Installation and Usage Manual" and also the file
+Please refer to ``Charm++ Installation and Usage Manual'' and also the file
 README in the source code for detailed instructions on how to compile Charm++.
-In short, the ``build" script is the main tool for compiling \charmpp{}.  You
-need to provide target and platform options: \begin{verbatim} ./build <target>
-<platform> [options ...] [charmc-options ...] \end{verbatim}
+In short, the ``build'' script is the main tool for compiling \charmpp{}.  One
+% #CLM# need to provide target and platform options: \begin{verbatim} ./build <target>
+        needs to provide {\em target} and {\em platform} selections: 
+\begin{verbatim} ./build <target> <platform> [options ...] [charmc-options ...] \end{verbatim}
 
-For example, to compile on a Linux machine, type:
+For example, to compile on a Linux machine, one would type:
 \begin{verbatim}
 ./build charm++ net-linux -O
 \end{verbatim}
 
-which builds essential \charmpp{} kernel using UDP sockets as 
-communication method, 
-alternatively, you can build Charm++ kernel on MPI using:
+\noindent
+% #CLM# which builds essential \charmpp{} kernel using UDP sockets as 
+        which builds essential \charmpp{} kernel using UDP sockets as the
+communication method; 
+% #CLM# alternatively, you can build Charm++ kernel on MPI using:
+        alternatively, it is possible to build the Charm++ kernel on MPI using:
 \begin{verbatim}
 ./build charm++ mpi-linux -O
 \end{verbatim}
 
-For other platforms, change net-linux to whatever platform you are compiling 
-on. See the charm/README file for a complete list of supported platforms.
+% #CLM# For other platforms, change net-linux to whatever platform you are compiling 
+        For other platforms, net-linux should be replaced by whatever platform is being used. 
+See the charm/README file for a complete list of supported platforms.
 
-\subsubsection{Build Only the BigSim Emulator}
+% #CLM# \subsubsection{Build Only the BigSim Emulator}
+        \subsubsection{Building Only the BigSim Emulator}
 
-BigSim emulator is implemented on top of Converse in Charm++.
-To compile BigSim emulator, one can compile emulator libraries
-directly on top of normal Charm++ using ``bigsim'' as the compilation
+The BigSim Emulator is implemented on top of Converse in Charm++.
+To compile the BigSim Emulator, one can compile Emulator libraries
+directly on top of normal \charmpp{} using ``bigsim'' as the compilation
 target, like
 \begin{verbatim}
 ./build bigsim net-linux -O
 \end{verbatim}
 
-With emulator libraries, one can write BigSim applications using its
-low level emulator message passing API.
+With Emulator libraries, one can write BigSim applications using its
+% #CLM# low level emulator message passing API.
+        low level machine API.
 
-\subsubsection{Build Charm++ on BigSim Emulator}
+% #CLM# \subsubsection{Build Charm++ on BigSim Emulator}
+        \subsubsection{Building Charm++ or AMPI on the BigSim Emulator}
 
 In order to build Charm++ on top of BigSim Emulator (which itself is 
 implemented on top of Converse), a special build option ``bigsim''
@@ -51,120 +61,164 @@ needs to be specified:
 ./build bigsim net-linux bigsim -O
 \end{verbatim}
 
-The first ``bigsim" is the compilation target that tells ``build" to
-compile BigSim emulator libraries in addition to \charmpp{} kernel libraries;
-The second ``bigsim" is a build option to platform ``net-linux", which tells
-``build" to build the Charm++ on top of BigSim Emulator. 
-To build AMPI on BigSim, use ``bgampi" as make target, which subsumes target
-of ``bigsim":
+The first ``bigsim'' is the compilation {\em target} that tells ``build'' to
+compile BigSim Emulator libraries in addition to \charmpp{} kernel libraries.
+The second ``bigsim'' is a build {\em option} to platform ``net-linux'', which tells
+``build'' to build Charm++ on top of the BigSim Emulator. 
+% #CLM# To build AMPI on BigSim, use ``bgampi'' as make target, which subsumes target
+        To build AMPI on BigSim, one should use ``bgampi'' as the make target, which subsumes the target
+``bigsim":
 \begin{verbatim}
 ./build bgampi net-linux bigsim -O
 \end{verbatim}
 
-For the above ``build" command, it creates a directory named 
+% #CLM# For the above ``build" command, it creates a directory named 
+        The above ``build" command creates a directory named 
 ``net-linux-bigsim" under charm, which contains all the header files and
 libraries needed for compiling a user application.
 
 \subsection{Compiling BigSim Applications}
 
 \charmpp{} provides a compiler script {\tt charmc} to compile all programs.
-
-There are three methods to write a BigSim application:
+% #CLM#
+As will be described in this subsection, there are three methods to write a BigSim application:
+(a) using the low level machine API, (b) using \charmpp{} or (c) using AMPI. Methods
+(b) and~(c) are essentially used to obtain traces from the BigSim Emulator, such that
+one can use those traces in a post-mortem simulation as explained in
+Section~\ref{bignetsim}.
 
 \subsubsection{Writing a BigSim application using low level machine API}
-The low level machine API mimics the actual machine low level programming
+% #CLM# The low level machine API mimics the actual machine low level programming
+        The original goal of the low level machine API was to mimic the BlueGene/C low level programming
 API. It is defined in section~\ref{bgemulator}. Writing a program in the 
-low level machine API, you just need to link \charmpp{}'s BigSim emulator
+% #CLM# low level machine API, you just need to link \charmpp{}'s BigSim emulator
+        low level machine API, one just needs to link \charmpp{}'s BigSim emulator
 libraries, which provide the emulation of the machine API using Converse as
 the communication layer.
 
-In order to link against the BigSim library, specify 
-\texttt{-language bigsim} as an argument to the {\tt charmc} linker, 
-for example:
+% #CLM# In order to link against the BigSim library, specify 
+        In order to link against the BigSim library, one must specify 
+% #CLM# \texttt{-language bigsim} as an argument to the {\tt charmc} linker, 
+        \texttt{-language bigsim} as an argument to the {\tt charmc} command, 
+% #CLM# for example:
+        such as:
 \begin{verbatim}
 charmc -o hello hello.C -language bigsim
 \end{verbatim}
 
-Sample applications in low level machine API can be found under directory
-charm/pgms/converse/bluegene.
+% #CLM# Sample applications in low level machine API can be found under directory
+        Sample applications in low level machine API can be found in directory
+% #CLM# charm/pgms/converse/bluegene.
+        charm/examples/bigsim/emulator/.
 
 \subsubsection{Writing a BigSim application in Charm++}
 
 One can write a normal \charmpp{} application which can automatically 
-run on the emulator after compilation. \charmpp{} implements
+% #CLM# run on the emulator after compilation. \charmpp{} implements
+        run on the BigSim Emulator after compilation. \charmpp{} implements
 an object-based message-driven execution model. In \charmpp{} applications,
 there are collections of C++ objects, which communicate by remotely invoking
-methods on other objects by messages.
+% #CLM# methods on other objects by messages.
+        methods on other objects via messages.
 
-In order to compile a program written in \charmpp{} on Blue Gene simulator, 
-specify \texttt{-language charm++} as an argument to the {\tt charmc} linker:
+% #CLM# In order to compile a program written in \charmpp{} on Blue Gene simulator, 
+                 To compile a program written in \charmpp{} on the BigSim Emulator, one
+specifies \texttt{-language charm++} as an argument to the {\tt charmc} command:
 \begin{verbatim}
 charmc -o hello hello.C -language charm++
 \end{verbatim}
-This will link both \charmpp{} runtime libraries and BigSim simulator 
+% #CLM# This will link both \charmpp{} runtime libraries and BigSim simulator 
+        This will link both \charmpp{} runtime libraries and BigSim Emulator
 libraries.
 
 Sample applications in \charmpp{} can be found under directory
-charm/pgms/charm++, specifically charm/pgms/charm++/littleMD.
-
-\subsubsection{Writing a Blue Gene application in MPI}
-
-One can also write a MPI application for Blue Gene Simulator.
-The Adaptive MPI, or AMPI is implemented on top of Charm++ that supports
-dynamic load balancing and multithreading for MPI applications. This is based
+% #CLM# charm/pgms/charm++, specifically charm/pgms/charm++/littleMD.
+        charm/examples/charm++, specifically charm/examples/charm++/littleMD.
+
+% #CLM# \subsubsection{Writing a Blue Gene application in MPI}
+        \subsubsection{Writing a BigSim application in MPI}
+
+% #CLM# One can also write a MPI application for Blue Gene Simulator.
+        One can also write an MPI application for the BigSim Emulator.
+% #CLM# The Adaptive MPI, or AMPI, is implemented on top of Charm++ that supports
+            Adaptive MPI, or AMPI, is implemented on top of Charm++, supporting
+% #CLM# dynamic load balancing and multithreading for MPI applications. This is based
+        dynamic load balancing and multithreading for MPI applications. Those are based
 on the user-level migrating threads and load balancing capabilities provided
 by the \charmpp{} framework. This allows legacy MPI programs to run 
-on top of Blue Gene \charmpp{} and take advantage of the \charmpp{}'s
+% #CLM# on top of Blue Gene \charmpp{} and take advantage of the \charmpp{}'s
+        on top of BigSim \charmpp{} and take advantage of the \charmpp{}'s
 virtualization and adaptive load balancing capability.
 
-Current AMPI implements most features in the MPI version 1.0, with a few
+% #CLM# Current AMPI implements most features in the MPI version 1.0, with a few
+        Currentlyi, AMPI implements most features in the MPI version 1.0, with a few
 extensions for migrating threads and asynchronous reduction.
 
-In order to compile an AMPI application on Blue Gene simulator, you need 
-to link against the AMPI library as well as Blue Gene \charmpp{} runtime
+% #CLM# In order to compile an AMPI application on Blue Gene simulator, you need 
+                 To compile an AMPI application for the BigSim Emulator, one needs
+% #CLM# to link against the AMPI library as well as Blue Gene \charmpp{} runtime
+        to link against the AMPI library as well as the BigSim \charmpp{} runtime
 libraries by specifying \texttt{-language ampi} as an argument to 
-the {\tt charmc} linker:
+% #CLM# the {\tt charmc} linker:
+        the {\tt charmc} command:
 \begin{verbatim}
 charmc -o hello hello.C -language ampi
 \end{verbatim}
 
 Sample applications in AMPI can be found under directory
-charm/pgms/charm++/ampi, specifically charm/pgms/charm++/Cjacobi3D.
+% #CLM# charm/pgms/charm++/ampi, specifically charm/pgms/charm++/Cjacobi3D.
+        charm/examples/charm++/ampi, specifically charm/examples/charm++/Cjacobi3D.
 
-\subsection{Run a BigSim Application}
+% #CLM# \subsection{Run a BigSim Application}
+        \subsection{Running a BigSim Application}
 
-To run a parallel Blue Gene application, \charmpp{} provides a utility program
-called {\tt charmrun} to start the parallel program. 
+% #CLM# To run a parallel Blue Gene application, \charmpp{} provides a utility program
+        To run a parallel BigSim application, \charmpp{} provides a utility program
+% #CLM# called {\tt charmrun} to start the parallel program. 
+        called {\tt charmrun} that starts the parallel execution.
 For detailed description on how to run a \charmpp{} application, 
 refer to the file charm/README in the source code distribution.
 
-To run a Blue Gene application, you need to specify these parameters to 
-{\tt charmrun} to define the simulated Blue Gene machine size:
+% #CLM# To run a Blue Gene application, you need to specify these parameters to 
+        To run a BigSim application, one needs to specify the following parameters to 
+% #CLM# {\tt charmrun} to define the simulated Blue Gene machine size:
+        {\tt charmrun} to define the simulated machine size:
 \begin{enumerate}
 \item {\tt +x, +y} and {\tt +z}:  define the size of the machine in three dimensions, these define the number of nodes along each dimension of the machine;
-\item {\tt +wth} and {\tt +cth}:  For one node, these two parameters define the number of worker processors({\tt +wth}) and the number of communication processors({\tt +cth}).
+\item {\tt +wth} and {\tt +cth}:  For one node, these two parameters define the number of worker processors~({\tt +wth}) and the number of communication processors~({\tt +cth}).
 \item {\tt +bgcorrect}: starts the simulation mode for performance prediction. Otherwise the program runs without doing parallel event simulation for performance prediction of the application.
 \item {\tt +bgwalltime}: used only in simulation mode, when specified, use wallclock measurement of the time taken on the simulating machine to estimate the time it takes to run on the target machine.
 \item {\tt +bgcounter}:  used only in simulation mode, when specified, use the performance counter to estimate the time on target machine. This is currently only supported when perfex is installed, like Origin2000.
 \end{enumerate}
 
-For example, to simulate a Blue Gene/L machine of size 64K in 40x40x40, with 
-one worker processor and one I/O processor on each node, and use 100 
-real processors to simulate:
+% #CLM# For example, to simulate a Blue Gene/L machine of size 64K in 40x40x40, with 
+        For example, to simulate a parallel machine of size 64K as 40x40x40, with 
+% #CLM# one worker processor and one I/O processor on each node, and use 100 
+        one worker processor and one communication processor on each node, and use 100 
+% #CLM# real processors to simulate:
+        real processors to run the simulation, the command to be issued should be:
 \begin{verbatim}
 ./charmrun +p100 ./hello +x40 +y40 +z40 +cth1 +wth1
 \end{verbatim}
 
-To run an AMPI program, you may also want to specify the number of virtual 
-processors to run the MPI by using {\tt +vp}, for example:
+% #CLM# To run an AMPI program, you may also want to specify the number of virtual 
+        To run an AMPI program, one may also want to specify the number of virtual 
+% #CLM# processors to run the MPI by using {\tt +vp}, for example:
+        processors to run the MPI code by using {\tt +vp}. As an example,
 \begin{verbatim}
 ./charmrun +p100 ./hello +x40 +y40 +z40 +cth1 +wth1 +vp 128000
 \end{verbatim}
-starts the simulation of Blue Gene/L of size 40x40x40 with 2 processors 
-in each node, running 128000 MPI threads (2 MPI threads on each Blue Gene node),
- using 100 real processors to simulate. In this case, {\tt MPI\_Comm\_size()}
-returns 128000 for {\tt MPI\_COMM\_WORLD}. If you donot specify the {\tt +vp}
-option, the number of virtual processors will be equal to the number of 
-processors of the simulated machine, in this case 64000.
+% #CLM# starts the simulation of Blue Gene/L of size 40x40x40 with 2 processors 
+        starts the simulation of a machine   of size 40x40x40 with one worker processor
+% #CLM# in each node, running 128000 MPI threads (2 MPI threads on each Blue Gene node),
+        in each node, running 128000 MPI tasks (2 MPI tasks on each node),
+% #CLM#  using 100 real processors to simulate. In this case, {\tt MPI\_Comm\_size()}
+         using 100 real processors to run the simulation. In this case, {\tt MPI\_Comm\_size()}
+returns 128000 for {\tt MPI\_COMM\_WORLD}.
+% #CLM# If you donot specify the {\tt +vp} option,
+        If the {\tt +vp} option is not specified,
+the number of virtual processors will be equal to the number of 
+% #CLM# processors of the simulated machine, in this case 64000.
+        worker processors of the simulated machine, in this case 64000.
 
 
index 83aaa4c173db25e3ac2f9824adf11cc5ac55b765..6659021910d4ca9e93b0d05c7401466b30914639 100644 (file)
@@ -3,12 +3,15 @@
 \input{../pplmanual}
 
 \title{BigSim Parallel Simulator for Extremely Large Parallel Machines}
-\version{1.00}
-\credits{Charm++ BigSim Emulator was developed by Arun Singla, Neelam Saboo
+\version{1.01}
+% #CLM# \credits{Charm++ BigSim Emulator was developed by Arun Singla, Neelam Saboo
+        \credits{The Charm++ BigSim Emulator was developed by Arun Singla, Neelam Saboo
 and Joshua Unger under the guidance of Prof. L. V. Kale. The new Converse 
-BigSim Emulator is completely rewritten by Gengbin Zheng. Converse BigSim 
+% #CLM# BigSim Emulator is completely rewritten by Gengbin Zheng. Converse BigSim 
+        BigSim Emulator was completely rewritten by Gengbin Zheng. The Converse BigSim 
 Emulator is the only version under maintenance now. Charm++ and Adaptive MPI
-(AMPI) was ported onto the BigSim Emulator by Gengbin Zheng. The parallel
+% #CLM# (AMPI) was ported onto the BigSim Emulator by Gengbin Zheng. The parallel
+        (AMPI) were ported onto the BigSim Emulator by Gengbin Zheng. The parallel
 performance simulator was developed by Gengbin Zheng and 
 Gunavardhan Kakulapati. A postmortem network simulator was developed by 
 Terry Wilmarth, Eric Bohm and Gengbin Zheng}
@@ -25,8 +28,9 @@ Terry Wilmarth, Eric Bohm and Gengbin Zheng}
 %Blue Gene/C was a proposed one million processor machine from IBM.
 
 Parallel machines with an extremely large number of processors are now
-being designed and built. For example, the BlueGene (BG/L) machine
-being built by IBM will have 64,000 dual-processor nodes with 360 teraflops
+being designed and built. For example, the BlueGene/L (BG/L) machine
+% #CLM# being built by IBM will have 64,000 dual-processor nodes with 360 teraflops
+built by IBM has 64,000 dual-processor nodes with 360 teraflops of
 peak performance. Another more radical design from IBM,
 code-named Cyclops (BlueGene/C), had over one million floating point units,
 fed by 8 million instructions streams supported by individual thread units,
@@ -35,10 +39,11 @@ targeting 1 petaflops of peak performance.
 
 It is important that one can study the programming issues and performance
 of parallel applications on such machines even before the machine is built.
-Thus, we have developed a parallel simulator -- BigSim to facilitate this research.
+Thus, we have developed a parallel simulator -- BigSim, to facilitate this research.
 
-Since our research was initiated by Blue Gene/C project, in this manual, 
-we also call our simulator as Blue Gene Simulator.
+% #CLM# Since our research was initiated by Blue Gene/C project, in this manual, 
+Since our research was initiated by the BlueGene/C project, in previous editions of this manual
+we also called our simulator as Blue Gene Simulator.
 Our simulator is capable of simulating a broad class of "Massively Parallel
 Processors-In-Memory", or MPPIM machines. 
 
@@ -46,50 +51,61 @@ Processors-In-Memory", or MPPIM machines.
 
 Our simulator system includes these components: 
 \begin{enumerate}
-\item a parallel emulator which emulates the low level machine API; 
+% #CLM# \item a parallel emulator which emulates the low level machine API; 
+        \item a parallel emulator which emulates a low level machine API targeting an architecture like BlueGene; 
 \item a message driven programming language (Charm++) running on top of the emulator; 
-\item adaptive MPI (an implementation of MPI on top of Charm++) environment; 
-\item a parallel online mode simulator for performance prediction. 
-\item a parallel postmoterm mode network simulator for performance prediction. 
+% #CLM# \item adaptive MPI (an implementation of MPI on top of Charm++) environment; 
+        \item the Adaptive MPI (an implementation of MPI on top of Charm++) environment; 
+% #CLM# Remove support for Online Simulator
+% #CLM# \item a parallel online mode simulator for performance prediction; 
+% #CLM# \item a parallel postmoterm mode network simulator for performance prediction. 
+        \item a parallel postmoterm mode simulator for performance prediction, including network simulation. 
 \end{enumerate}
 
 \subsection{History}
 
-The first version of Blue Gene emulator was written in Charm++, a 
-parallel object language in fall, 2001. 
+% #CLM# The first version of Blue Gene emulator was written in Charm++, a 
+        The first version of the BlueGene emulator was written in Charm++, a 
+parallel object language, in fall 2001. 
 
-The second version of Blue Gene emulator was completely rewritten on top 
+% #CLM# The second version of Blue Gene emulator was completely rewritten on top 
+        The second version of the BlueGene emulator was completely rewritten on top 
 of Converse instead of Charm++ in spring 2002. 
-While the API supported by the original emulator remains almost same,
+% #CLM# While the API supported by the original emulator remains almost same,
+        While the API supported by the original emulator remains almost the same,
 many new features were added.
 % - support of thread-committed messages that 
 %can be send to a specific thread in a Blue Gene node; support of Blue Gene 
 %node level broadcast.
 The new emulator was implemented on a portable low layer communication 
-library - Converse in order to achieve better 
+library - Converse, in order to achieve better 
 performance by avoiding the cross layer overhead.
 %Another advantage is that the lighter weighted emulator makes it easier
 %to port higher level of programming language onto the emulator.
 
-Charm++ was soon ported to the emulator in 2002 which provided the
+% #CLM# Charm++ was soon ported to the emulator in 2002 which provided the
+        Charm++ was ported to the emulator in 2002, providing the
  first parallel language model on top of the emulator.
 
 A performance simulation capability was added to the emulator in spring 2003.
 The new simulator was renamed to BigSim at the same time.
 During the same year, we developed a POSE-based postmortem mode network
-simulator called BigNetSim.
-
+simulator called BigNetSim. In fall 2006, we renamed BigNetSim as simply
+BigSim simulator.
 
 In the following sections, we will first describe how to download and compile
-Blue Gene simulator(Section ~\ref{install}). Section~\ref{bgemulator} will describe
-the low level machine API in detail. 
+% #CLM# Blue Gene simulator(Section ~\ref{install}). Section~\ref{bgemulator} will describe
+    the BigSim system (Section~\ref{install}). Section~\ref{bgemulator} describes
+% #CLM# the low level machine API in detail. 
+    the BigSim Emulator and the low level machine API in detail. 
 
 
 \input{install}
 \input{emulator}
-\input{simulator}
-\input{bignetsim}
+% #CLM# REMOVE ONLINE SIMULATOR; MOVE BGAPI HERE
+% #CLM# \input{simulator}
 \input{bgapi}
+\input{bignetsim}
 
 \input{index}
 \end{document}