b3137979a6d6f28317e0f6ab33e916497ba3d138
[charm.git] / README.bigsim
1 =======================================================================
2
3 HOW TO INSTALL AND RUN EMULATION/SIMULATION WITH BIGSIM
4 =======================================================
5
6 PPL, December 2006 - Send questions to ppl@cs.uiuc.edu
7
8 These are a few notes on how to get going with BigSim for
9 emulation and simulation of MPI application codes. Part (A)
10 covers BigSim installation, while part (B) covers usage of
11 the software installed in part (A), for emulation and
12 simulation.
13
14
15 A) INSTALLING BIGSIM:
16 ====================
17
18 The BigSim package depends on parts of Charm++. So, assuming
19 that the application is an MPI code, one needs to build
20 Charm++ with support for AMPI. As an example, on a
21 Myrinet-based Linux cluster, this can be done with
22
23    ./build AMPI net-linux gm -O
24
25 A special Charm++ build is necessary for emulation with BigSim.
26 This new build needs to use the BigSim machine-layer,
27 because the emulator needs to run on top of that. This new
28 build can be produced by
29
30    ./build AMPI net-linux gm bigemulator -O
31
32 The first argument ("AMPI") is a target meaning that MPI
33 applications will be used. The "bigemulator" argument implies
34 the BigSim machine-layer. This should produce a sub-directory
35 such as "net-linux-bigemulator-gm", with a valid Charm++ instance.
36
37 Next, the regular Charm++ build (net-linux-gm in our example)
38 needs to be complemented with a few more libaries from BigSim
39 and with the Pose discrete-event simulator. These pieces can be
40 built, respectively, with:
41
42    ./build bgampi net-linux gm -O
43    ./build pose net-linux gm -O
44
45 Access to the discrete-event simulation is realized via a
46 Charm++ package originally named BigNetSim. Assuming that the
47 'subversion' (svn) package is available, this package can
48 be obtained from the Web with a subversion checkout such as
49
50    svn co https://charm.cs.uiuc.edu/svn/repos/BigNetSim/
51
52 In the subdir 'trunk/' created by the checkout, the file
53 Makefile.common must be edited so that 'CHARMBASE' points
54 to the regular Charm++ installation. Having that done, one
55 chooses a topology in that subdir (e.g. BlueGene) by doing
56 a "cd" into the corresponding directory (e.g. 'cd BlueGene').
57 Inside that directory, one should simply "make". This
58 will produce file "../tmp/bigsimulator". That file, together
59 with file "BlueGene/netconfig.vc", will be used during a
60 simulation.
61
62
63
64 B) USING BIGSIM:
65 ===============
66
67 The recommended usage of BigSim with MPI codes may consist of
68 three steps: verifying that the code works under AMPI, running
69 an emulation of the code, and running an actual simulation.
70 As an option, a fourth step consists in analyzing performance
71 of the simulated code in a post-mortem fashion with the
72 Projections tool. These various steps are described below.
73
74
75 B-1) Verifying that the code works with AMPI:
76 --------------------------------------------
77
78 First, the MPI code must be compiled by charmc or one of the
79 AMPI scripts, using the flag "-swapglobals" (assuming
80 a ELF-compatible system), like
81
82    mpicc -o prog prog.c -swapglobals
83
84 To run the code under AMPI, a test-run should have VP>P, to
85 ensure that the results are still correct even when there is
86 more than one VP per physical processor:
87
88    charmrun +p4 prog +vp8
89
90 Notice that both 'mpicc' and 'charmrun' must be taken from
91 the regular Charm++ build in step (A), i.e. 'net-linux-gm'
92 in our example.
93
94
95 B-2) Running a BigSim emulation:
96 --------------------------------
97
98 Here, one must point his/her path to the Charm++ instance
99 produced for emulation; in our example of step (A), this
100 would be under subdir "net-linux-bigsim-gm". Next, one must
101 compile again the MPI code, preparing it for the emulation:
102
103    mpicc -o prog_emul prog.c -swapglobals
104
105 (it should be noticed that this time a proper 'mpicc' will
106 be invoked, assuming that the path is set correctly)
107
108 Now, all that is needed is to run this new executable under
109 Charm++, for the emulation:
110
111    charmrun +p4 prog_emul +vp16 +x16 +y1 +z1 +cth1 +wth1 +bglog
112
113 Argument "+vp16" indicates the number of processors of the
114 hypothetical (future) system. Arguments "x/y/z" indicate the
115 dimensions of the future machine, while "cth/wth" indicate,
116 respectively, the number of compute and I/O processors in
117 each node of that future machine.
118
119 Argument "+bglog" must be used so that BigSim logfiles get
120 created. These files are named 'bgTrace', bgTrace0,
121 'bgTrace1', ... 'bgTrace{Q-1}' where "Q" is the number of
122 processors running the emulation.
123
124 The output produced in this execution shows an emulation
125 of the MPI code, in this case assuming a future machine
126 with 16 processors.
127
128
129 B-3) Running a BigSim simulation:
130 --------------------------------
131
132 To run a simulation, one needs files "bigsimulator" and
133 "netconfig" produced in step (A). Those two files must be
134 placed in the same directory as the BigSim tracefiles (i.e.
135 'bgTrace*' files). File "netconfig" may have to be created
136 (by copying it from file BlueGene/netconfig.vc) and edited,
137 to at least match the geometry of nodes assumed for the
138 future machine. Actual simulation execution is started by:
139
140    charmrun +p2 bigsimulator 0 0
141
142 which will run the simulation assuming a "latency-only"
143 mode. The simulation can be run on any number of processors,
144 regardless of the number of processors used in the emulation
145 or in the future target machine.
146
147 To run the simulation using BlueGene's actual network, the
148 command should be
149
150    charmrun +p2 bigsimulator 1 0
151
152 Either of these commands will print, in stdout, information
153 about the predicted execution time (Global Virtual Time, or
154 GVT). Notice that the number of processors used to run the
155 simulation can be chosen independently of the number of
156 processors used in the emulation or in the future machine.
157
158 To analyze how changes in the network characteritics may
159 affect performance, one may edit file 'netconfig' and repeat
160 the simulation. In particular, to change the topology of the
161 network for a topology different than the one originally
162 assumed in the emulation, one should have a line like the
163 following in file 'netconfig': OVERRIDE_TRACE_TOPOLOGY 1
164
165
166 B-4) Generating performance data for Projections:
167 ------------------------------------------------
168
169 To generate Projections-compatible traces that can be
170 visualized in Projections, two steps should be changed in the
171 described procedure, as follows. In the emulation phase (B-2),
172 one should create the application adding '-tracemore projections'
173 to the build line, such as
174
175    mpicc -o prog_emul prog.c -swapglobals -tracemode projections
176
177 With this, during the emulation, Projection-files with extensions
178 '.sts' and '.log' will be created, such as 'prog_emul.*.log'.
179 All of these files *must* be copied into the same directory
180 where the simulation will be run (same directory containing files
181 'bigsimulator' and 'netconfig').
182
183 Then, when running the simulation (B-3), flag '-projname' should
184 be added, such as
185
186    charmrun +p2 bigsimulator 0 0 -projname prog_emul
187
188 This form of simulation will generate new files with extensions
189 ".sts" and ".log" (such as 'prog_emul-bg.*.log') which can be
190 visualized in Projections. 
191
192