cleaning up of the manual
[charm.git] / doc / bigsim / install.tex
1 \section{BigSim Simulator Installation and Usage}
2 \label{install}
3
4 \subsection{Installing Charm++ and BigSim}
5
6 % #CLM# BigSim Simulator is distributed as a part of the Charm++ standard distribution.
7     The BigSim Simulator is distributed as part of the Charm++ standard distribution.
8 One needs to download Charm++ and compile the BigSim Simulator.
9 % #CLM# One should begin with downloading Charm++ from the website:
10 This process should begin with downloading Charm++ from the website:
11 http://charm.cs.uiuc.edu.
12
13 Please refer to ``Charm++ Installation and Usage Manual'' and also the file
14 README in the source code for detailed instructions on how to compile Charm++.
15 In short, the ``build'' script is the main tool for compiling \charmpp{}.  One
16 % #CLM# need to provide target and platform options: \begin{verbatim} ./build <target>
17         needs to provide {\em target} and {\em platform} selections: 
18 \begin{verbatim} ./build <target> <platform> [options ...] [charmc-options ...] \end{verbatim}
19
20 For example, to compile on a Linux machine, one would type:
21 \begin{verbatim}
22 ./build charm++ net-linux -O
23 \end{verbatim}
24
25 \noindent
26 % #CLM# which builds essential \charmpp{} kernel using UDP sockets as 
27         which builds essential \charmpp{} kernel using UDP sockets as the
28 communication method; 
29 % #CLM# alternatively, you can build Charm++ kernel on MPI using:
30         alternatively, it is possible to build the Charm++ kernel on MPI using:
31 \begin{verbatim}
32 ./build charm++ mpi-linux -O
33 \end{verbatim}
34
35 % #CLM# For other platforms, change net-linux to whatever platform you are compiling 
36         For other platforms, net-linux should be replaced by whatever platform is being used. 
37 See the charm/README file for a complete list of supported platforms.
38
39 % #CLM# \subsubsection{Build Only the BigSim Emulator}
40         \subsubsection{Building Only the BigSim Emulator}
41
42 The BigSim Emulator is implemented on top of Converse in Charm++.
43 To compile the BigSim Emulator, one can compile Emulator libraries
44 directly on top of normal \charmpp{} using ``bigsim'' as the compilation
45 target, like
46 \begin{verbatim}
47 ./build bigsim net-linux -O
48 \end{verbatim}
49
50 With Emulator libraries, one can write BigSim applications using its
51 % #CLM# low level emulator message passing API.
52         low level machine API.
53
54 % #CLM# \subsubsection{Build Charm++ on BigSim Emulator}
55         \subsubsection{Building Charm++ or AMPI on the BigSim Emulator}
56
57 In order to build Charm++ on top of BigSim Emulator (which itself is 
58 implemented on top of Converse), a special build option ``bigsim''
59 needs to be specified:
60 \begin{verbatim}
61 ./build bigsim net-linux bigsim -O
62 \end{verbatim}
63
64 The first ``bigsim'' is the compilation {\em target} that tells ``build'' to
65 compile BigSim Emulator libraries in addition to \charmpp{} kernel libraries.
66 The second ``bigsim'' is a build {\em option} to platform ``net-linux'', which tells
67 ``build'' to build Charm++ on top of the BigSim Emulator. 
68 % #CLM# To build AMPI on BigSim, use ``bgampi'' as make target, which subsumes target
69         To build AMPI on BigSim, one should use ``bgampi'' as the make target, which subsumes the target
70 ``bigsim":
71 \begin{verbatim}
72 ./build bgampi net-linux bigsim -O
73 \end{verbatim}
74
75 % #CLM# For the above ``build" command, it creates a directory named 
76         The above ``build" command creates a directory named 
77 ``net-linux-bigsim" under charm, which contains all the header files and
78 libraries needed for compiling a user application.
79
80 \subsection{Compiling BigSim Applications}
81
82 \charmpp{} provides a compiler script {\tt charmc} to compile all programs.
83 % #CLM#
84 As will be described in this subsection, there are three methods to write a BigSim application:
85 (a) using the low level machine API, (b) using \charmpp{} or (c) using AMPI. Methods
86 (b) and~(c) are essentially used to obtain traces from the BigSim Emulator, such that
87 one can use those traces in a post-mortem simulation as explained in
88 Section~\ref{bignetsim}.
89
90 \subsubsection{Writing a BigSim application using low level machine API}
91 % #CLM# The low level machine API mimics the actual machine low level programming
92         The original goal of the low level machine API was to mimic the BlueGene/C low level programming
93 API. It is defined in section~\ref{bgemulator}. Writing a program in the 
94 % #CLM# low level machine API, you just need to link \charmpp{}'s BigSim emulator
95         low level machine API, one just needs to link \charmpp{}'s BigSim emulator
96 libraries, which provide the emulation of the machine API using Converse as
97 the communication layer.
98
99 % #CLM# In order to link against the BigSim library, specify 
100         In order to link against the BigSim library, one must specify 
101 % #CLM# \texttt{-language bigsim} as an argument to the {\tt charmc} linker, 
102         \texttt{-language bigsim} as an argument to the {\tt charmc} command, 
103 % #CLM# for example:
104         such as:
105 \begin{verbatim}
106 charmc -o hello hello.C -language bigsim
107 \end{verbatim}
108
109 % #CLM# Sample applications in low level machine API can be found under directory
110         Sample applications in low level machine API can be found in directory
111 % #CLM# charm/pgms/converse/bluegene.
112         charm/examples/bigsim/emulator/.
113
114 \subsubsection{Writing a BigSim application in Charm++}
115
116 One can write a normal \charmpp{} application which can automatically 
117 % #CLM# run on the emulator after compilation. \charmpp{} implements
118         run on the BigSim Emulator after compilation. \charmpp{} implements
119 an object-based message-driven execution model. In \charmpp{} applications,
120 there are collections of C++ objects, which communicate by remotely invoking
121 % #CLM# methods on other objects by messages.
122         methods on other objects via messages.
123
124 % #CLM# In order to compile a program written in \charmpp{} on Blue Gene simulator, 
125                  To compile a program written in \charmpp{} on the BigSim Emulator, one
126 specifies \texttt{-language charm++} as an argument to the {\tt charmc} command:
127 \begin{verbatim}
128 charmc -o hello hello.C -language charm++
129 \end{verbatim}
130 % #CLM# This will link both \charmpp{} runtime libraries and BigSim simulator 
131         This will link both \charmpp{} runtime libraries and BigSim Emulator
132 libraries.
133
134 Sample applications in \charmpp{} can be found under directory
135 % #CLM# charm/pgms/charm++, specifically charm/pgms/charm++/littleMD.
136         charm/examples/bigsim, specifically charm/examples/bigsim/emulator/littleMD.
137
138 % #CLM# \subsubsection{Writing a Blue Gene application in MPI}
139         \subsubsection{Writing a BigSim application in MPI}
140
141 % #CLM# One can also write a MPI application for Blue Gene Simulator.
142         One can also write an MPI application for the BigSim Emulator.
143 % #CLM# The Adaptive MPI, or AMPI, is implemented on top of Charm++ that supports
144             Adaptive MPI, or AMPI, is implemented on top of Charm++, supporting
145 % #CLM# dynamic load balancing and multithreading for MPI applications. This is based
146         dynamic load balancing and multithreading for MPI applications. Those are based
147 on the user-level migrating threads and load balancing capabilities provided
148 by the \charmpp{} framework. This allows legacy MPI programs to run 
149 % #CLM# on top of Blue Gene \charmpp{} and take advantage of the \charmpp{}'s
150         on top of BigSim \charmpp{} and take advantage of the \charmpp{}'s
151 virtualization and adaptive load balancing capability.
152
153 % #CLM# Current AMPI implements most features in the MPI version 1.0, with a few
154         Currently, AMPI implements most features in the MPI version 1.0, with a few
155 extensions for migrating threads and asynchronous reduction.
156
157 % #CLM# In order to compile an AMPI application on Blue Gene simulator, you need 
158                  To compile an AMPI application for the BigSim Emulator, one needs
159 % #CLM# to link against the AMPI library as well as Blue Gene \charmpp{} runtime
160         to link against the AMPI library as well as the BigSim \charmpp{} runtime
161 libraries by specifying \texttt{-language ampi} as an argument to 
162 % #CLM# the {\tt charmc} linker:
163         the {\tt charmc} command:
164 \begin{verbatim}
165 charmc -o hello hello.C -language ampi
166 \end{verbatim}
167
168 Sample applications in AMPI can be found under directory
169 % #CLM# charm/pgms/charm++/ampi, specifically charm/pgms/charm++/Cjacobi3D.
170         charm/examples/ampi, specifically charm/examples/ampi/pingpong.
171
172 % #CLM# \subsection{Run a BigSim Application}
173         \subsection{Running a BigSim Application}
174
175 % #CLM# To run a parallel Blue Gene application, \charmpp{} provides a utility program
176         To run a parallel BigSim application, \charmpp{} provides a utility program
177 % #CLM# called {\tt charmrun} to start the parallel program. 
178         called {\tt charmrun} that starts the parallel execution.
179 For detailed description on how to run a \charmpp{} application, 
180 refer to the file charm/README in the source code distribution.
181
182 % #CLM# To run a Blue Gene application, you need to specify these parameters to 
183         To run a BigSim application, one needs to specify the following parameters to 
184 % #CLM# {\tt charmrun} to define the simulated Blue Gene machine size:
185         {\tt charmrun} to define the simulated machine size:
186 \begin{enumerate}
187 \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;
188 \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}).
189 \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.
190 \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.
191 \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.
192 \end{enumerate}
193
194 % #CLM# For example, to simulate a Blue Gene/L machine of size 64K in 40x40x40, with 
195         For example, to simulate a parallel machine of size 64K as 40x40x40, with 
196 % #CLM# one worker processor and one I/O processor on each node, and use 100 
197         one worker processor and one communication processor on each node, and use 100 
198 % #CLM# real processors to simulate:
199         real processors to run the simulation, the command to be issued should be:
200 \begin{verbatim}
201 ./charmrun +p100 ./hello +x40 +y40 +z40 +cth1 +wth1
202 \end{verbatim}
203
204 % #CLM# To run an AMPI program, you may also want to specify the number of virtual 
205         To run an AMPI program, one may also want to specify the number of virtual 
206 % #CLM# processors to run the MPI by using {\tt +vp}, for example:
207         processors to run the MPI code by using {\tt +vp}. As an example,
208 \begin{verbatim}
209 ./charmrun +p100 ./hello +x40 +y40 +z40 +cth1 +wth1 +vp 128000
210 \end{verbatim}
211 % #CLM# starts the simulation of Blue Gene/L of size 40x40x40 with 2 processors 
212         starts the simulation of a machine   of size 40x40x40 with one worker processor
213 % #CLM# in each node, running 128000 MPI threads (2 MPI threads on each Blue Gene node),
214         in each node, running 128000 MPI tasks (2 MPI tasks on each node),
215 % #CLM#  using 100 real processors to simulate. In this case, {\tt MPI\_Comm\_size()}
216          using 100 real processors to run the simulation. In this case, {\tt MPI\_Comm\_size()}
217 returns 128000 for {\tt MPI\_COMM\_WORLD}.
218 % #CLM# If you do not specify the {\tt +vp} option,
219         If the {\tt +vp} option is not specified,
220 the number of virtual processors will be equal to the number of 
221 % #CLM# processors of the simulated machine, in this case 64000.
222         worker processors of the simulated machine, in this case 64000.
223
224