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