reduced size
[charm.git] / doc / bigsim / install.tex
1 \section{BigSim Emulator Installation and Usage}
2 \label{install}
3
4 \subsection{Installing Charm++ and BigSim}
5
6     The BigSim Emulator is distributed as part of the Charm++ standard
7 distribution.  One needs to download Charm++ and compile the BigSim Simulator.
8 This process should begin with downloading Charm++ from the website:
9 http://charm.cs.uiuc.edu.
10
11 Please refer to ``Charm++ Installation and Usage Manual'' and also the file
12 README in the source code for detailed instructions on how to compile Charm++.
13 In short, the ``build'' script is the main tool for compiling \charmpp{}.  One
14 needs to provide {\em target} and {\em platform} selections: 
15 \begin{verbatim} ./build <target> <platform> [options ...] [charmc-options ...] \end{verbatim}
16
17 For example, to compile on a 64-bit Linux machine, one would type:
18 \begin{verbatim}
19 ./build charm++ net-linux-x86_64 -O2
20 \end{verbatim}
21
22 \noindent which builds essential \charmpp{} kernel using UDP sockets as the
23 communication method; alternatively, it is possible to build the Charm++ kernel
24 on MPI using:
25 \begin{verbatim}
26 ./build charm++ mpi-linux-x86_64 -O2
27 \end{verbatim}
28
29 For other platforms, net-linux-x86\_64 should be replaced by whatever platform is being used. 
30 See the charm/README file for a complete list of supported platforms.
31
32 \subsubsection{Building Only the BigSim Emulator}
33
34 The BigSim Emulator is implemented on top of Converse in Charm++.  To compile
35 the BigSim Emulator, one can compile Emulator libraries directly on top of
36 normal \charmpp{} using ``bgampi'' as the compilation target, like
37 \begin{verbatim}
38 ./build bgampi net-linux-x86_64 -O2
39 \end{verbatim}
40
41 With Emulator libraries, one can write BigSim applications using its
42 low level machine API.
43
44 \subsubsection{Building Charm++ or AMPI on the BigSim Emulator}
45
46 In order to build Charm++ or AMPI on top of BigSim Emulator (which itself is
47 implemented on top of Converse), a special build option ``bigemulator'' needs
48 to be specified:
49 \begin{verbatim}
50 ./build bgampi net-linux-x86_64 bigemulator -O2
51 \end{verbatim}
52
53 The ``bgampi'' option is the compilation {\em target} that tells ``build'' to
54 compile BigSim Emulator libraries in addition to \charmpp{} kernel libraries.
55 The ``bigemulator'' option is a build {\em option} to platform ``net-linux'',
56 which tells ``build'' to build Charm++ on top of the BigSim Emulator. 
57
58 The above ``build" command creates a directory named
59 ``net-linux-x86\_64-bigemulator" under charm, which contains all the header
60 files and libraries needed for compiling a user application.
61
62 \subsection{Compiling BigSim Applications}
63
64 \charmpp{} provides a compiler script {\tt charmc} to compile all programs.  As
65 will be described in this subsection, there are three methods to write a BigSim
66 application: (a) using the low level machine API, (b) using \charmpp{} or (c)
67 using AMPI. Methods (b) and~(c) are essentially used to obtain traces from the
68 BigSim Emulator, such that one can use those traces in a post-mortem simulation
69 as explained in Section~\ref{bignetsim}.
70
71 \subsubsection{Writing a BigSim application using low level machine API}
72 The original goal of the low level machine API was to mimic the BlueGene/C low
73 level programming API. It is defined in section~\ref{bgemulator}. Writing a
74 program in the low level machine API, one just needs to link \charmpp{}'s
75 BigSim emulator libraries, which provide the emulation of the machine API using
76 Converse as the communication layer.
77
78 In order to link against the BigSim library, one must specify
79 \texttt{-language bigsim} as an argument to the {\tt charmc} command, for
80 example:
81
82 \begin{verbatim}
83 charmc -o hello hello.C -language bigsim
84 \end{verbatim}
85
86 Sample applications in low level machine API can be found in the directory
87 charm/examples/bigsim/emulator/.
88
89 \subsubsection{Writing a BigSim application in Charm++}
90
91 One can write a normal \charmpp{} application which can automatically run on
92 the BigSim Emulator after compilation. \charmpp{} implements an object-based
93 message-driven execution model. In \charmpp{} applications, there are
94 collections of C++ objects, which communicate by remotely invoking methods on
95 other objects via messages.
96
97 To compile a program written in \charmpp{} on the BigSim Emulator, one
98 specifies \texttt{-language charm++} as an argument to the {\tt charmc}
99 command:
100 \begin{verbatim}
101 charmc -o hello hello.C -language charm++
102 \end{verbatim}
103 This will link both \charmpp{} runtime libraries and BigSim Emulator libraries.
104
105 Sample applications in \charmpp{} can be found in the directory
106 charm/examples/bigsim, specifically charm/examples/bigsim/emulator/littleMD.
107
108 \subsubsection{Writing a BigSim application in MPI}
109
110 One can also write an MPI application for the BigSim Emulator.  Adaptive MPI,
111 or AMPI, is implemented on top of Charm++, supporting dynamic load balancing
112 and multithreading for MPI applications. Those are based on the user-level
113 migrating threads and load balancing capabilities provided by the \charmpp{}
114 framework. This allows legacy MPI programs to run on top of BigSim \charmpp{}
115 and take advantage of the \charmpp{}'s virtualization and adaptive load
116 balancing capability.
117
118 Currently, AMPI implements most features in the MPI version 1.0, with a few
119 extensions for migrating threads and asynchronous reduction.
120
121 To compile an AMPI application for the BigSim Emulator, one needs to link
122 against the AMPI library as well as the BigSim \charmpp{} runtime libraries by
123 specifying \texttt{-language ampi} as an argument to the {\tt charmc} command:
124 \begin{verbatim}
125 charmc -o hello hello.C -language ampi
126 \end{verbatim}
127
128 Sample applications in AMPI can be found in the directory charm/examples/ampi,
129 specifically charm/examples/ampi/pingpong.
130
131 \subsection{Running a BigSim Application}
132
133 To run a parallel BigSim application, \charmpp{} provides a utility program
134 called {\tt charmrun} that starts the parallel execution.  For detailed
135 description on how to run a \charmpp{} application, refer to the file
136 charm/README in the source code distribution.
137
138 To run a BigSim application, one needs to specify the following parameters to
139 {\tt charmrun} to define the simulated machine size:
140
141 \begin{enumerate}
142
143 \item {\tt +vp}: define the number of processors of the hypothetical (future)
144 system
145 \item {\tt +x, +y} and {\tt +z}:  optionally define the size of the machine in
146 three dimensions, these define the number of nodes along each dimension of the
147 machine (assuming a torus/mesh topology);
148 \item {\tt +wth} and {\tt +cth}:  For one node, these two parameters define the
149 number of worker processors~({\tt +wth}) and the number of communication
150 processors~({\tt +cth}).
151 \item {\tt +bglog}: used so that BigSim logfiles get created
152 \item {\tt +bgcorrect}: starts the simulation mode for performance prediction.
153 Otherwise the program runs without doing parallel event simulation for
154 performance prediction of the application.
155 \item {\tt +bgwalltime}: used only in simulation mode, when specified, use
156 wallclock measurement of the time taken on the simulating machine to estimate
157 the time it takes to run on the target machine.
158 \item {\tt +bgcounter}:  used only in simulation mode, when specified, use the
159 performance counter to estimate the time on target machine. This is currently
160 only supported when perfex is installed, like Origin2000.
161 \end{enumerate}
162
163 For example, to simulate a parallel machine of size 64K as 40x40x40, with one
164 worker processor and one communication processor on each node, and use 100 real
165 processors to run the simulation, the command to be issued should be:
166 \begin{verbatim}
167 ./charmrun +p100 ./hello +x40 +y40 +z40 +cth1 +wth1
168 \end{verbatim}
169
170 To run an AMPI program, one may also want to specify the number of virtual
171 processors to run the MPI code by using {\tt +vp}. As an example,
172 \begin{verbatim}
173 ./charmrun +p100 ./hello +x40 +y40 +z40 +cth1 +wth1 +vp 128000
174 \end{verbatim}
175 \noindent starts the simulation of a machine   of size 40x40x40 with one worker
176 processor in each node, running 128000 MPI tasks (2 MPI tasks on each node),
177 using 100 real processors to run the simulation. In this case, {\tt
178 MPI\_Comm\_size()} returns 128000 for {\tt MPI\_COMM\_WORLD}.  If the {\tt +vp}
179 option is not specified, the number of virtual processors will be equal to the
180 number of worker processors of the simulated machine, in this case 64000.
181