Added a comment about building the sequential version of bigsimulator
[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. It may be useful to set the variable SEQUENTIAL
61 to 1 in Makefile.common to build a sequential(non-parallel)
62 version of bigsimulator.
63
64
65
66 B) USING BIGSIM:
67 ===============
68
69 The recommended usage of BigSim with MPI codes may consist of
70 three steps: verifying that the code works under AMPI, running
71 an emulation of the code, and running an actual simulation.
72 As an option, a fourth step consists in analyzing performance
73 of the simulated code in a post-mortem fashion with the
74 Projections tool. These various steps are described below.
75
76
77 B-1) Verifying that the code works with AMPI:
78 --------------------------------------------
79
80 First, the MPI code must be compiled by charmc or one of the
81 AMPI scripts, using the flag "-swapglobals" (assuming
82 a ELF-compatible system), like
83
84    mpicc -o prog prog.c -swapglobals
85
86 To run the code under AMPI, a test-run should have VP>P, to
87 ensure that the results are still correct even when there is
88 more than one VP per physical processor:
89
90    charmrun +p4 prog +vp8
91
92 Notice that both 'mpicc' and 'charmrun' must be taken from
93 the regular Charm++ build in step (A), i.e. 'net-linux-gm'
94 in our example.
95
96
97 B-2) Running a BigSim emulation:
98 --------------------------------
99
100 Here, one must point his/her path to the Charm++ instance
101 produced for emulation; in our example of step (A), this
102 would be under subdir "net-linux-bigsim-gm". Next, one must
103 compile again the MPI code, preparing it for the emulation:
104
105    mpicc -o prog_emul prog.c -swapglobals
106
107 (it should be noticed that this time a proper 'mpicc' will
108 be invoked, assuming that the path is set correctly)
109
110 Now, all that is needed is to run this new executable under
111 Charm++, for the emulation:
112
113    charmrun +p4 prog_emul +vp16 +x16 +y1 +z1 +cth1 +wth1 +bglog
114
115 Argument "+vp16" indicates the number of processors of the
116 hypothetical (future) system. Arguments "x/y/z" indicate the
117 dimensions of the future machine, while "cth/wth" indicate,
118 respectively, the number of compute and I/O processors in
119 each node of that future machine.
120
121 Argument "+bglog" must be used so that BigSim logfiles get
122 created. These files are named 'bgTrace', bgTrace0,
123 'bgTrace1', ... 'bgTrace{Q-1}' where "Q" is the number of
124 processors running the emulation.
125
126 The output produced in this execution shows an emulation
127 of the MPI code, in this case assuming a future machine
128 with 16 processors.
129
130
131 B-3) Running a BigSim simulation:
132 --------------------------------
133
134 To run a simulation, one needs files "bigsimulator" and
135 "netconfig" produced in step (A). Those two files must be
136 placed in the same directory as the BigSim tracefiles (i.e.
137 'bgTrace*' files). File "netconfig" may have to be created
138 (by copying it from file BlueGene/netconfig.vc) and edited,
139 to at least match the geometry of nodes assumed for the
140 future machine. Actual simulation execution is started by:
141
142    charmrun +p2 bigsimulator 0 0
143
144 which will run the simulation assuming a "latency-only"
145 mode. The simulation can be run on any number of processors,
146 regardless of the number of processors used in the emulation
147 or in the future target machine.
148
149 To run the simulation using BlueGene's actual network, the
150 command should be
151
152    charmrun +p2 bigsimulator 1 0
153
154 Either of these commands will print, in stdout, information
155 about the predicted execution time (Global Virtual Time, or
156 GVT). Notice that the number of processors used to run the
157 simulation can be chosen independently of the number of
158 processors used in the emulation or in the future machine.
159
160 To analyze how changes in the network characteritics may
161 affect performance, one may edit file 'netconfig' and repeat
162 the simulation. In particular, to change the topology of the
163 network for a topology different than the one originally
164 assumed in the emulation, one should have a line like the
165 following in file 'netconfig': OVERRIDE_TRACE_TOPOLOGY 1
166
167
168 B-4) Generating performance data for Projections:
169 ------------------------------------------------
170
171 To generate Projections-compatible traces that can be
172 visualized in Projections, two steps should be changed in the
173 described procedure, as follows. In the emulation phase (B-2),
174 one should create the application adding '-tracemore projections'
175 to the build line, such as
176
177    mpicc -o prog_emul prog.c -swapglobals -tracemode projections
178
179 With this, during the emulation, Projection-files with extensions
180 '.sts' and '.log' will be created, such as 'prog_emul.*.log'.
181 All of these files *must* be copied into the same directory
182 where the simulation will be run (same directory containing files
183 'bigsimulator' and 'netconfig').
184
185 Then, when running the simulation (B-3), flag '-projname' should
186 be added, such as
187
188    charmrun +p2 bigsimulator 0 0 -projname prog_emul
189
190 This form of simulation will generate new files with extensions
191 ".sts" and ".log" (such as 'prog_emul-bg.*.log') which can be
192 visualized in Projections. 
193
194