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