fixed a lot of minor errors
[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 BigSim Simulator is part of Charm++ distribution as a runtime 
7 library. One needs to download Charm++ and compile BigSim simulator.
8
9 You should begin with downloading Charm++ from the website:
10 http://charm.cs.uiuc.edu
11
12 Please refer to ``Charm++ Installation and Usage Manual" and also the file README
13 in the source code for detailed instructions on how to compile Charm++.
14 In short, the ``build" script is the main tool for compiling \charmpp{}.
15 You need to provide target and platform options:
16 \begin{verbatim}
17 ./build <target> <platform> [options ...] [charmc-options ...]
18 \end{verbatim}
19
20 For example, to compile on a Linux machine, type:
21 \begin{verbatim}
22 ./build charm++ net-linux -O
23 \end{verbatim}
24
25 which builds essential \charmpp{} kernel using UDP sockets as 
26 communication method, 
27 alternatively, you can build Charm++ kernel on MPI using:
28 \begin{verbatim}
29 ./build charm++ mpi-linux -O
30 \end{verbatim}
31
32 For other platforms, change net-linux to whatever platform you are compiling 
33 on. See the charm/README file for a complete list of supported platforms.
34
35 \subsubsection{Compile Charm++ Emulator Only}
36
37 BigSim emulator is implemented on top of Converse in Charm++, 
38 to compile BigSim emulator only, one can compile emulator libraries
39 directly on top of normal Charm++ using ``bluegene'' as the compilation
40 target, like
41 \begin{verbatim}
42 ./build bluegene net-linux -O
43 \end{verbatim}
44
45 With emulator libraries, one can write BigSim applications using its
46 low level emulator message passing API.
47
48 \subsubsection{Compile Charm++ on BigSim Emulator}
49
50 In order to build Charm++ on top of BigSim Emulator (which itself is 
51 implemented on top of Converse), a special build option ``bluegene''
52 needs to be specified:
53 \begin{verbatim}
54 ./build bluegene net-linux bluegene -O
55 \end{verbatim}
56
57 The first ``bluegene" is the compilation target that tells ``build" to
58 compile BigSim emulator libraries in addition to \charmpp{} kernel;
59 The second ``bluegene" is a build option to platform ``net-linux", which tells
60 ``build" to compile the Charm++ on top of BigSim Emulator. 
61 To build AMPI on BigSim, use ``bgampi" as make target, which subsumes target
62 of ``bluegene":
63 \begin{verbatim}
64 ./build bgampi net-linux bluegene -O
65 \end{verbatim}
66
67 For the above ``build" command, it creates a directory named 
68 ``net-linux-bluegene" under charm, which contains all the header files and
69 libraries needed for compiling a user application.
70
71 \subsection{Compiling BigSim Applications}
72
73 \charmpp{} provides a compiler script {\tt charmc} to compile all programs.
74
75 There are three methods to write a BigSim application:
76
77 \subsubsection{Writing a BigSim application using low level machine API}
78 The low level machine API mimics the actual machine low level programming
79 API. It is defined in section~\ref{bgemulator}. Writing a program in the 
80 low level machine API, you just need to link \charmpp{}'s Blue Gene emulator
81 library, which provides the emulation of the machine API using Converse as
82 the communication layer.
83
84 In order to link against the Blue Gene library, specify 
85 \texttt{-language bluegene} as an argument to the {\tt charmc} linker, 
86 for example:
87 \begin{verbatim}
88 charmc -o hello hello.C -language bluegene
89 \end{verbatim}
90
91 Sample applications in low level machine API can be found under directory
92 charm/pgms/converse/bluegene.
93
94 \subsubsection{Writing a Blue Gene application in Charm++}
95
96 One can write a normal \charmpp{} application which can automatically 
97 run on the emulator after compilation. \charmpp{} implements
98 an object-based message-driven execution model. In \charmpp{} applications,
99 there are collections of C++ objects, which communicate by remotely invoking
100 methods on other objects by messages.
101
102 In order to compile a program written in \charmpp{} on Blue Gene simulator, 
103 specify \texttt{-language charm++} as an argument to the {\tt charmc} linker:
104 \begin{verbatim}
105 charmc -o hello hello.C -language charm++
106 \end{verbatim}
107 This will link both \charmpp{} runtime libraries and Blue Gene simulator 
108 library.
109
110 Sample applications in \charmpp{} can be found under directory
111 charm/pgms/charm++, specifically charm/pgms/charm++/littleMD.
112
113 \subsubsection{Writing a Blue Gene application in MPI}
114
115 One can also write a MPI application for Blue Gene Simulator.
116 The Adaptive MPI, or AMPI is implemented on top of Charm++ that supports
117 dynamic load balancing and multithreading for MPI applications. This is based
118 on the user-level migrating threads and load balancing capabilities provided
119 by the \charmpp{} framework. This allows legacy MPI programs to run 
120 on top of Blue Gene \charmpp{} and take advantage of the \charmpp{}'s
121 virtualization and adaptive load balancing capability.
122
123 Current AMPI implements most features in the MPI version 1.0, with a few
124 extensions for migrating threads and asynchronous reduction.
125
126 In order to compile an AMPI application on Blue Gene simulator, you need 
127 to link against the AMPI library as well as Blue Gene \charmpp{} runtime
128 libraries by specifying \texttt{-language ampi} as an argument to 
129 the {\tt charmc} linker:
130 \begin{verbatim}
131 charmc -o hello hello.C -language ampi
132 \end{verbatim}
133
134 Sample applications in AMPI can be found under directory
135 charm/pgms/charm++/ampi, specifically charm/pgms/charm++/Cjacobi3D.
136
137 \subsection{Run a BigSim Application}
138
139 To run a parallel Blue Gene application, \charmpp{} provides a utility program
140 called {\tt charmrun} to start the parallel program. 
141 For detailed description on how to run a \charmpp{} application, 
142 refer to the file charm/README in the source code distribution.
143
144 To run a Blue Gene application, you need to specify these parameters to 
145 {\tt charmrun} to define the simulated Blue Gene machine size:
146 \begin{enumerate}
147 \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;
148 \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}).
149 \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.
150 \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.
151 \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.
152 \end{enumerate}
153
154 For example, to simulate a Blue Gene/L machine of size 64K in 40x40x40, with 
155 one worker processor and one I/O processor on each node, and use 100 
156 real processors to simulate:
157 \begin{verbatim}
158 ./charmrun +p100 ./hello +x40 +y40 +z40 +cth1 +wth1
159 \end{verbatim}
160
161 To run an AMPI program, you may also want to specify the number of virtual 
162 processors to run the MPI by using {\tt +vp}, for example:
163 \begin{verbatim}
164 ./charmrun +p100 ./hello +x40 +y40 +z40 +cth1 +wth1 +vp 128000
165 \end{verbatim}
166 starts the simulation of Blue Gene/L of size 40x40x40 with 2 processors 
167 in each node, running 128000 MPI threads (2 MPI threads on each Blue Gene node),
168  using 100 real processors to simulate. In this case, {\tt MPI\_Comm\_size()}
169 returns 128000 for {\tt MPI\_COMM\_WORLD}. If you donot specify the {\tt +vp}
170 option, the number of virtual processors will be equal to the number of 
171 processors of the simulated machine, in this case 64000.
172
173