ZC EM Post API: Add examples for each registration mode
[charm.git] / README.bigsim
1 =======================================================================
2
3 HOW TO INSTALL AND RUN EMULATION/SIMULATION WITH BIGSIM
4 =======================================================
5
6 Updated: February 2009 - Send questions to charm@cs.illinois.edu
7
8 These are a few notes on how to get going with BigSim for emulation and
9 simulation of MPI application codes. Part (A) covers BigSim installation, while
10 part (B) covers usage of the software installed in part (A), for emulation and
11 simulation.
12
13
14 A) INSTALLING BIGSIM:
15 ====================
16
17 Skip ahead to section C for quick start instructions.
18
19 The BigSim package depends on Charm++. So, assuming that the application can be
20 an MPI or Charm++ code, one needs to build Charm++ with support for AMPI. We
21 need to compile two different versions of Charm, one for emulating the user
22 application and the other for using the traces for the simulation.
23
24 A special Charm++ build is necessary for emulation with BigSim.  This new build
25 needs to use the BigSim machine-layer, because the emulator needs to run on top
26 of that. On a 64-bit Linux machine, this new build can be produced by
27
28    ./build bgampi netlrts-linux-x86_64 bigemulator -O2
29
30 The first argument ("bgampi") is a target meaning that bigsim, charm++ and LIBS
31 will be compiled. The "bigemulator" argument implies that the BigSim machine
32 layer will be used for running the programs. This should produce a
33 sub-directory such as "netlrts-linux-x86_64-bigemulator", with a valid Charm++
34 instance.
35
36 To compile the simulator which is called BigSimulator (or BigNetSim), we need
37 the regular Charm++ build (netlrts-linux-x86_64 in our example).  It needs to be
38 complemented with a few more libaries from BigSim and with the Pose
39 discrete-event simulator. These pieces can be built, respectively, with:
40
41    ./build bgampi netlrts-linux-x86_64 -O2
42    ./build pose netlrts-linux-x86_64 -O2
43
44 Access to the discrete-event simulation is realized via a Charm++ package
45 originally named BigNetSim (now called BigSimulator). Assuming that the
46 'subversion' (svn) package is available, this package can be obtained from the
47 Web with a subversion checkout such as
48
49    svn co https://charm.cs.illinois.edu/svn/repos/BigNetSim/
50
51 In the subdir 'trunk/' created by the checkout, the file Makefile.common must
52 be edited so that 'CHARMBASE' points to the regular Charm++ installation.
53 Having that done, one chooses a topology in that subdir (e.g. BlueGene for a
54 torus topology) by doing a "cd" into the corresponding directory (e.g. 'cd
55 BlueGene').  Inside that directory, one should simply "make". This will produce
56 the binary "../tmp/bigsimulator". That file, together with file
57 "BlueGene/netconfig.vc", will be used during a simulation. It may be useful to
58 set the variable SEQUENTIAL to 1 in Makefile.common to build a sequential
59 (non-parallel) version of bigsimulator.
60
61
62 B) USING BIGSIM:
63 ===============
64
65 The recommended usage of BigSim with MPI codes may consist of three steps:
66 verifying that the code works under AMPI, running an emulation of the code, and
67 running an actual simulation. As an option, a fourth step consists in
68 analyzing performance of the simulated code in a post-mortem fashion with the
69 Projections tool. These various steps are described below.
70
71
72 B-1) Verifying that the code works with AMPI:
73 --------------------------------------------
74
75 First, the MPI code must be compiled by charmc or one of the AMPI scripts,
76 using the flag "-swapglobals" (assuming a ELF-compatible system), like
77
78    mpicc -o prog prog.c -swapglobals
79
80 To run the code under AMPI, a test-run should have VP>P, to ensure that the
81 results are still correct even when there is more than one VP per physical
82 processor:
83
84    charmrun +p4 prog +vp8
85
86 Notice that both 'mpicc' and 'charmrun' must be taken from the regular Charm++
87 build in step (A), i.e. 'netlrts-linux-x86_64' in our example.
88
89
90 B-2) Running a BigSim emulation:
91 --------------------------------
92
93 Here, one must point his/her path to the Charm++ instance produced for
94 emulation; in our example of step (A), this would be under subdir
95 "netlrts-linux-x86_64-bigemulator". Next, one must compile again the MPI code,
96 preparing it for the emulation:
97
98    mpicc -o prog_emul prog.c -swapglobals
99
100 (it should be noticed that this time a proper 'mpicc' will be invoked, assuming
101 that the path is set correctly)
102
103 Now, all that is needed is to run this new executable under Charm++, for the
104 emulation:
105
106    charmrun +p4 prog_emul +vp16 +x16 +y1 +z1 +cth1 +wth1 +bglog
107
108 Argument "+vp16" indicates the number of processors of the hypothetical
109 (future) system. Arguments "x/y/z" indicate the dimensions of the future
110 machine, while "cth/wth" indicate, respectively, the number of compute and I/O
111 processors in each node of that future machine.
112
113 Argument "+bglog" must be used so that BigSim logfiles get created. These files
114 are named 'bgTrace', bgTrace0, 'bgTrace1', ... 'bgTrace{Q-1}' where "Q" is the
115 number of processors running the emulation.
116
117 The output produced in this execution shows an emulation of the MPI code, in
118 this case assuming a future machine with 16 processors.
119
120
121 B-3) Running a BigSim simulation:
122 --------------------------------
123
124 a) All network models
125
126 To run a simulation, one needs the binary "bigsimulator" and the file
127 "netconfig" produced in step (A). Those two must be placed in the same
128 directory as the BigSim tracefiles (i.e.  'bgTrace*' files). File "netconfig"
129 may have to be created (by copying it from file BlueGene/netconfig.vc) and
130 edited, to at least match the geometry of nodes assumed for the future machine.
131 Actual simulation execution is started by:
132
133    ./charmrun +p2 ./bigsimulator 0 0
134
135 which will run the simulation assuming a "latency-only" mode. The simulation
136 can be run on any number of processors, regardless of the number of processors
137 used in the emulation or in the future target machine.
138
139 To run the simulation using BlueGene's actual network, the command should be
140
141    ./charmrun +p2 ./bigsimulator 1 0
142
143 Either of these commands will print, in stdout, information about the predicted
144 execution time (Global Virtual Time, or GVT). Notice that the number of
145 processors used to run the simulation can be chosen independently of the number
146 of processors used in the emulation or in the future machine.
147
148 To analyze how changes in the network characteritics may affect performance,
149 one may edit file 'netconfig' and repeat the simulation. In particular, to
150 change the topology of the network for a topology different than the one
151 originally assumed in the emulation, one should have a line like the following
152 in file 'netconfig': OVERRIDE_TRACE_TOPOLOGY 1
153
154 b) Simple latency model
155
156 To use the simple latency model, follow the setup procedure in part (a) of this
157 section, noting that the files are located in the trunk/SimpleLatency
158 directory.  This will produce the "bigsimulator" file.
159
160 The command line parameters used for this model are different.  The format is
161 as follows:
162
163    [charmrun +p#] bigsimulator -lat <latency> -bw <bandwidth>
164                   [-cpp <cost per packet> -psize <packet size>]
165                   [-winsize <window size>] [-skip] [-print_params]
166
167 Latency (lat)         - type double; in microseconds
168 Bandwidth (bw)        - type double; in GB/s
169 Cost per packet (cpp) - type double; in microseconds
170 Packet size (psize)   - type int; in bytes
171 Window size (winsize) - type int; in log entries
172
173 The implemented equation is: lat + (N/bw) + cpp*(N/psize)
174
175 Latency and bandwidth are required.  If cost per packet is given, then packet
176 size must be given, as well.  Otherwise, cost per packet defaults to 0.0.
177 Packet size, if given, must be a positive integer.
178
179 The -winsize flag allows the user to specify the size of the window (number of
180 log entries) used when reading in the bgTrace log files.  This is useful if the
181 log files are large.  If -winsize is not specified, the value defaults to 0,
182 which indicates that no windowing will be used (i.e., there will be one window
183 for each time line that is equal to the size of the time line).
184
185 As with the second parameter in the examples of part (a) of this section, the
186 -skip flag indicates that the simulation should skip forward to the time stamp
187 set during trace creation (see the BigSim tutorial talk from the 2008 Charm++
188 workshop).  If -skip is not included, then no skipping will occur.
189
190 The -print_params flag is provided for debugging convenience.  When present,
191 the simple latency model parameters will be displayed during simulation
192 initilization.
193
194
195 B-4) Generating performance data for Projections:
196 ------------------------------------------------
197
198 To generate Projections-compatible traces that can be visualized in
199 Projections, two steps should be changed in the described procedure, as
200 follows. In the emulation phase (B-2), one should create the application adding
201 '-tracemore projections' to the build line, such as
202
203    mpicc -o prog_emul prog.c -swapglobals -tracemode projections
204
205 With this, during the emulation, Projection-files with extensions '.sts' and
206 '.log' will be created, such as 'prog_emul.*.log'.  All of these files *must*
207 be copied into the same directory where the simulation will be run (same
208 directory containing files 'bigsimulator' and 'netconfig').
209
210 Then, when running the simulation (B-3), flag '-projname' should be added, such
211 as
212
213    charmrun +p2 bigsimulator 0 0 -projname prog_emul
214
215 This form of simulation will generate new files with extensions ".sts" and
216 ".log" (such as 'prog_emul-bg.*.log') which can be visualized in Projections. 
217
218
219 C) QUICK START:
220 ===============
221
222 This is a step-by-step quick tutorial for simple usage of BigSim simulation framework and visualizing its Projections output logs.
223 For more information, please refer to the BigSim and Projections manuals.
224
225 1- build charm (and AMPI) with bigemulator and bigsim (replace "linux" with "darwin" for mac):
226         cd charm
227         ./build charm++ netlrts-linux-x86_64 bigemulator bigsim
228         ./build AMPI netlrts-linux-x86_64 bigemulator bigsim
229
230 2- compile your code using charm or AMPI compilers located in "netlrts-linux-x86_64-bigemulator-bigsim/bin", for example:
231         cd tests/ampi/jacobi3d; make 
232
233 3- run your application emulating the target machine, for example:
234         ./charmrun +p1 jacobi 4 4 2 5 +vp32 +x32 +y1 +z1 +cth1 +wth1 +bglog
235
236 4- download BigSim's simulator
237         git clone https://charm.cs.illinois.edu/gerrit/BigFastSim
238
239 5- build BigFastSim:
240         cd BigFastSim/Release
241         vim makefile  #change CHARMPATH=$(HOME)/charm/netlrts-linux-x86_64-bigemulator-bigsim/
242         make
243
244 6- copy simulator to trace files' directory:
245         cd ~/charm/tests/ampi/jacobi3d
246         cp ~/BigFastSim/Release/seqSimulator .
247
248 7- run the simulator with projections output: (to see other options such as changing latency and bandwidth run "./seqSimulator -help")
249         ./seqSimulator -tproj
250
251 8- download and make Projections:
252         git clone https://charm.cs.illinois.edu/gerrit/projections
253         cd projections
254         ant
255
256 9- run Projections:
257         ./bin/projections #open tproj.sts file
258
259 After opening the symbol file (file/open <tproj.sts>), you can use different features of Projections such as tools/Timelines.
260