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