Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
add svg and some description for dragonfly topology
[simgrid.git] / docs / source / tuto_smpi.rst
1 .. _usecase_smpi:
2
3 Simulating MPI Applications
4 ===========================
5
6 .. warning:: This document is still in early stage. You can try to
7    take this tutorial, but should not be surprised if things fall short.
8    It will be completed for the next release, v3.22, released by the end
9    of 2018.
10
11 Discover SMPI
12 -------------
13
14 SimGrid can not only :ref:`simulate algorithms <usecase_simalgo>`, but
15 it can also be used to execute real MPI applications on top of
16 virtual, simulated platforms with the SMPI module. Even complex
17 C/C++/F77/F90 applications should run out of the box in this
18 environment. In fact, almost all proxy apps provided by the `ExaScale
19 Project <https://proxyapps.exascaleproject.org/>`_ only require minor
20 modifications to `run on top of SMPI
21 <https://github.com/simgrid/SMPI-proxy-apps/>`_.
22
23 This setting permits to debug your MPI applications in a perfectly
24 reproducible setup, with no Heisenbugs. Enjoy the full Clairevoyance
25 provided by the simulator while running what-if analysis on platforms
26 that are still to be built! Several `production-grade MPI applications
27 <https://framagit.org/simgrid/SMPI-proxy-apps#full-scale-applications>`_
28 use SimGrid for their integration and performance testing.
29
30 MPI 2.2 is already partially covered: over 160 primitives are
31 supported. Some parts of the standard are still missing: MPI-IO, MPI3
32 collectives, spawning ranks, and some others. If one of the functions
33 you use is still missing, please drop us an email. We may find the
34 time to implement it for you.
35
36 Multi-threading support is very limited in SMPI. Only funneled
37 applications are supported: at most one thread per rank can issue any
38 MPI calls. For better timing predictions, your application should even
39 be completely mono-threaded. Using OpenMP (or pthreads directly) may
40 greatly decrease SimGrid predictive power. That may still be OK if you
41 only plan to debug your application in a reproducible setup, without
42 any performance-related analysis.
43
44 How does it work?
45 .................
46
47 In SMPI, communications are simulated while computations are
48 emulated. This means that while computations occur as they would in
49 the real systems, communication calls are intercepted and achived by
50 the simulator.
51
52 To start using SMPI, you just need to compile your application with
53 ``smpicc`` instead of ``mpicc``, or with ``smpiff`` instead of
54 ``mpiff``, or with ``smpicxx`` instead of ``mpicxx``. Then, the only
55 difference between the classical ``mpirun`` and the new ``smpirun`` is
56 that it requires a new parameter ``-platform`` with a file describing
57 the simulated platform on which your application shall run.
58
59 Internally, all ranks of your application are executed as threads of a
60 single unix process. That's not a problem if your application has
61 global variables, because ``smpirun`` loads one application instance
62 per MPI rank as if it was another dynamic library. Then, MPI
63 communication calls are implemented using SimGrid: data is exchanged
64 through memory copy, while the simulator's performance models are used
65 to predict the time taken by each communications. Any computations
66 occuring between two MPI calls are benchmarked, and the corresponding
67 time is reported into the simulator.
68
69 .. image:: /tuto_smpi/img/big-picture.svg
70    :align: center          
71
72 Describing Your Platform
73 ------------------------
74
75 As a SMPI user, you are supposed to provide a description of your
76 simulated platform, that is mostly a set of simulated hosts and network
77 links with some performance characteristics. SimGrid provides a plenty
78 of :ref:`documentation <platform>` and examples (in the
79 `examples/platforms <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms>`_
80 source directory), and this section only shows a small set of introductory
81 examples.
82
83 Feel free to skip this section if you want to jump right away to usage
84 examples.
85
86 Simple Example with 3 hosts
87 ...........................
88
89 At the most basic level, you can describe your simulated platform as a
90 graph of hosts and network links. For instance:
91
92 .. image:: /tuto_smpi/3hosts.png
93    :align: center
94
95 .. literalinclude:: /tuto_smpi/3hosts.xml
96    :language: xml
97
98 Note the way in which hosts, links, and routes are defined in
99 this XML. All hosts are defined with a speed (in Gflops), and links
100 with a latency (in us) and bandwidth (in MBytes per second). Other
101 units are possible and written as expected. Routes specify the list of
102 links encountered from one route to another. Routes are symmetrical by
103 default.
104
105 Cluster with a Crossbar
106 .......................
107
108 A very common parallel computing platform is a homogeneous cluster in
109 which hosts are interconnected via a crossbar switch with as many
110 ports as hosts, so that any disjoint pairs of hosts can communicate
111 concurrently at full speed. For instance:
112
113 .. literalinclude:: ../../examples/platforms/cluster_crossbar.xml
114    :language: xml
115    :lines: 1-3,18-
116
117 One specifies a name prefix and suffix for each host, and then give an
118 integer range. In the example the cluster contains 65535 hosts (!),
119 named ``node-0.simgrid.org`` to ``node-65534.simgrid.org``. All hosts
120 have the same power (1 Gflop/sec) and are connected to the switch via
121 links with same bandwidth (125 MBytes/sec) and latency (50
122 microseconds).
123
124 .. todo::
125
126    Add the picture.
127
128 Cluster with a Shared Backbone
129 ..............................
130
131 Another popular model for a parallel platform is that of a set of
132 homogeneous hosts connected to a shared communication medium, a
133 backbone, with some finite bandwidth capacity and on which
134 communicating host pairs can experience contention. For instance:
135
136
137 .. literalinclude:: ../../examples/platforms/cluster_backbone.xml
138    :language: xml
139    :lines: 1-3,18-
140
141 The only differences with the crossbar cluster above are the ``bb_bw``
142 and ``bb_lat`` attributes that specify the backbone characteristics
143 (here, a 500 microseconds latency and a 2.25 GByte/sec
144 bandwidth). This link is used for every communication within the
145 cluster. The route from ``node-0.simgrid.org`` to ``node-1.simgrid.org``
146 counts 3 links: the private link of ``node-0.simgrid.org``, the backbone
147 and the private link of ``node-1.simgrid.org``.
148            
149 .. todo::
150
151    Add the picture.
152
153 Torus Cluster
154 .............
155
156 Many HPC facilities use torus clusters to reduce sharing and
157 performance loss on concurrent internal communications. Modeling this
158 in SimGrid is very easy. Simply add a ``topology="TORUS"`` attribute
159 to your cluster. Configure it with the ``topo_parameters="X,Y,Z"``
160 attribute, where ``X``, ``Y`` and ``Z`` are the dimension of your
161 torus.
162
163 .. image:: ../../examples/platforms/cluster_torus.svg
164    :align: center
165
166 .. literalinclude:: ../../examples/platforms/cluster_torus.xml
167    :language: xml
168
169 Note that in this example, we used ``loopback_bw`` and
170 ``loopback_lat`` to specify the characteristics of the loopback link
171 of each node (i.e., the link allowing each node to communicate with
172 itself). We could have done so in previous example too. When no
173 loopback is given, the communication from a node to itself is handled
174 as if it were two distinct nodes: it goes twice through the private
175 link and through the backbone (if any).
176
177 Fat-Tree Cluster
178 ................
179
180 This topology was introduced to reduce the amount of links in the
181 cluster (and thus reduce its price) while maintaining a high bisection
182 bandwidth and a relatively low diameter. To model this in SimGrid,
183 pass a ``topology="FAT_TREE"`` attribute to your cluster. The
184 ``topo_parameters=#levels;#downlinks;#uplinks;link count`` follows the
185 semantic introduced in the `Figure 1B of this article
186 <http://webee.eedev.technion.ac.il/wp-content/uploads/2014/08/publication_574.pdf>`_.
187
188 Here is the meaning of this example: ``2 ; 4,4 ; 1,2 ; 1,2``
189
190 - That's a two-level cluster (thus the initial ``2``).
191 - Routers are connected to 4 elements below them, regardless of its
192   level. Thus the ``4,4`` component that is used as
193   ``#downlinks``. This means that the hosts are grouped by 4 on a
194   given router, and that there is 4 level-1 routers (in the middle of
195   the figure).
196 - Hosts are connected to only 1 router above them, while these routers
197   are connected to 2 routers above them (thus the ``1,2`` used as
198   ``#uplink``).
199 - Hosts have only one link to their router while every path between a
200   level-1 routers and level-2 routers use 2 parallel links. Thus the
201   ``1,2`` that is used as ``link count``.
202
203 .. image:: ../../examples/platforms/cluster_fat_tree.svg
204    :align: center
205
206 .. literalinclude:: ../../examples/platforms/cluster_fat_tree.xml
207    :language: xml
208    :lines: 1-3,10-
209
210
211 Dragonfly Cluster
212 .................
213
214 This topology was introduced to further reduce the amount of links
215 while maintaining a high bandwidth for local communications. To model
216 this in SimGrid, pass a ``topology="DRAGONFLY"`` attribute to your
217 cluster. It's based on the implementation of the topology used on 
218 Cray XC systems, described in paper
219 ``Cray Cascade: A scalable HPC system based on a Dragonfly network`` :
220
221 System description follows the format ``topo_parameters=#groups;#chassis;#routers;#nodes``
222
223 For example, ``3,4 ; 3,2 ; 3,1 ; 2``:
224
225 - ``3,4``: There are 3 groups with 4 links between each (blue level).
226   Links to nth group are attached to the nth router of the group 
227   on our implementation.
228 - ``3,2``: In each group, there are 3 chassis with 2 links between each nth router
229   of each group (black level)
230 - ``3,1``: In each chassis, 3 routers are connected together with a single link
231   (green level)
232 - ``2``: Each router has two nodes attached (single link) 
233
234 .. image:: ../../examples/platforms/cluster_dragonfly.svg
235    :align: center
236
237 .. literalinclude:: ../../examples/platforms/cluster_dragonfly.xml
238    :language: xml
239
240 Final Word
241 ..........
242
243 We only glanced over the abilities offered by SimGrid to describe the
244 platform topology. Other networking zones model non-HPC platforms
245 (such as wide area networks, ISP network comprising set-top boxes, or
246 even your own routing schema). You can interconnect several networking
247 zones in your platform to form a tree of zones, that is both a time-
248 and memory-efficient representation of distributed platforms. Please
249 head to the dedicated :ref:`documentation <platform>` for more
250 information.
251
252 Hands-on!
253 ---------
254
255 It is time to start using SMPI yourself. For that, you first need to
256 install it somehow, and then you will need a MPI application to play with.
257
258 Using Docker
259 ............
260
261 The easiest way to take the tutorial is to use the dedicated Docker
262 image. Once you `installed Docker itself
263 <https://docs.docker.com/install/>`_, simply do the following:
264
265 .. code-block:: shell
266
267    docker pull simgrid/tuto-smpi
268    docker run -it --rm --name simgrid --volume ~/smpi-tutorial:/source/tutorial simgrid/tuto-smpi bash
269
270 This will start a new container with all you need to take this
271 tutorial, and create a ``smpi-tutorial`` directory in your home on
272 your host machine that will be visible as ``/source/tutorial`` within the
273 container.  You can then edit the files you want with your favorite
274 editor in ``~/smpi-tutorial``, and compile them within the
275 container to enjoy the provided dependencies.
276
277 .. warning::
278
279    Any change to the container out of ``/source/tutorial`` will be lost
280    when you log out of the container, so don't edit the other files!
281
282 All needed dependencies are already installed in this container
283 (SimGrid, the C/C++/Fortran compilers, make, pajeng and R). Vite being
284 only optional in this tutorial, it is not installed to reduce the
285 image size. 
286
287 The container also include the example platform files from the
288 previous section as well as the source code of the NAS Parallel
289 Benchmarks. These files are available under
290 ``/source/simgrid-template-smpi`` in the image. You should copy it to
291 your working directory when you first log in:
292
293 .. code-block:: shell
294
295    cp -r /source/simgrid-template-smpi/* /source/tutorial
296    cd /source/tutorial
297
298 Using your Computer Natively
299 ............................
300
301 To take the tutorial on your machine, you first need to :ref:`install
302 SimGrid <install>`, the C/C++/Fortran compilers and also ``pajeng`` to
303 visualize the traces. You may want to install `Vite
304 <http://vite.gforge.inria.fr/>`_ to get a first glance at the
305 traces. The provided code template requires make to compile. On
306 Debian and Ubuntu for example, you can get them as follows:
307
308 .. code-block:: shell
309
310    sudo apt install simgrid pajeng make gcc g++ gfortran vite
311
312 To take this tutorial, you will also need the platform files from the
313 previous section as well as the source code of the NAS Parallel
314 Benchmarks. Just  clone `this repository
315 <https://framagit.org/simgrid/simgrid-template-smpi>`_  to get them all:
316
317 .. code-block:: shell
318
319    git clone git@framagit.org:simgrid/simgrid-template-smpi.git
320    cd simgrid-template-smpi/
321
322 If you struggle with the compilation, then you should double check
323 your :ref:`SimGrid installation <install>`.  On need, please refer to
324 the :ref:`Troubleshooting your Project Setup
325 <install_yours_troubleshooting>` section.
326
327 Lab 0: Hello World
328 ------------------
329
330 It is time to simulate your first MPI program. Use the simplistic
331 example `roundtrip.c
332 <https://framagit.org/simgrid/simgrid-template-smpi/raw/master/roundtrip.c?inline=false>`_
333 that comes with the template.
334
335 .. literalinclude:: /tuto_smpi/roundtrip.c
336    :language: c
337
338 Compiling and Executing
339 .......................
340               
341 Compiling the program is straightforward (double check your
342 :ref:`SimGrid installation <install>` if you get an error message):
343
344
345 .. code-block:: shell
346                 
347   $ smpicc -O3 roundtrip.c -o roundtrip
348
349
350 Once compiled, you can simulate the execution of this program on 16
351 nodes from the ``cluster_crossbar.xml`` platform as follows:
352
353 .. code-block:: shell
354
355    $ smpirun -np 16 -platform cluster_crossbar.xml -hostfile cluster_hostfile ./roundtrip
356
357 - The ``-np 16`` option, just like in regular MPI, specifies the
358   number of MPI processes to use. 
359 - The ``-hostfile cluster_hostfile`` option, just like in regular
360   MPI, specifies the host file. If you omit this option, ``smpirun``
361   will deploy the application on the first machines of your platform.
362 - The ``-platform cluster_crossbar.xml`` option, **which doesn't exist
363   in regular MPI**, specifies the platform configuration to be
364   simulated. 
365 - At the end of the line, one finds the executable name and
366   command-line arguments (if any -- roundtrip does not expect any arguments).
367
368 Feel free to tweak the content of the XML platform file and the
369 program to see the effect on the simulated execution time. It may be
370 easier to compare the executions with the extra option
371 ``--cfg=smpi/display_timing:yes``.  Note that the simulation accounts
372 for realistic network protocol effects and MPI implementation
373 effects. As a result, you may see "unexpected behavior" like in the
374 real world (e.g., sending a message 1 byte larger may lead to
375 significant higher execution time).
376
377 Lab 1: Visualizing LU
378 ---------------------
379
380 We will now simulate a larger application: the LU benchmark of the NAS
381 suite. The version provided in the code template was modified to
382 compile with SMPI instead of the regular MPI. Compare the difference
383 between the original ``config/make.def.template`` and the
384 ``config/make.def`` that was adapted to SMPI. We use ``smpiff`` and
385 ``smpicc`` as compilers, and don't pass any additional library.
386
387 Now compile and execute the LU benchmark, class S (i.e., for `small
388 data size
389 <https://www.nas.nasa.gov/publications/npb_problem_sizes.html>`_) with
390 4 nodes.
391
392 .. code-block:: shell
393
394    $ make lu NPROCS=4 CLASS=S
395    (compilation logs)
396    $ smpirun -np 4 -platform ../cluster_backbone.xml bin/lu.S.4
397    (execution logs)
398
399 To get a better understanding of what is going on, activate the
400 vizualization tracing, and convert the produced trace for later
401 use:
402
403 .. code-block:: shell
404
405    smpirun -np 4 -platform ../cluster_backbone.xml -trace --cfg=tracing/filename:lu.S.4.trace bin/lu.S.4
406    pj_dump --ignore-incomplete-links lu.S.4.trace | grep State > lu.S.4.state.csv
407
408 You can then produce a Gantt Chart with the following R chunk. You can
409 either copy/paste it in a R session, or `turn it into a Rscript executable
410 <https://swcarpentry.github.io/r-novice-inflammation/05-cmdline/>`_ to
411 run it again and again.
412
413 .. code-block:: R
414
415    library(ggplot2)
416
417    # Read the data
418    df_state = read.csv("lu.S.4.state.csv", header=F, strip.white=T)
419    names(df_state) = c("Type", "Rank", "Container", "Start", "End", "Duration", "Level", "State");
420    df_state = df_state[!(names(df_state) %in% c("Type","Container","Level"))]
421    df_state$Rank = as.numeric(gsub("rank-","",df_state$Rank))
422
423    # Draw the Gantt Chart
424    gc = ggplot(data=df_state) + geom_rect(aes(xmin=Start, xmax=End, ymin=Rank, ymax=Rank+1,fill=State))
425
426    # Produce the output
427    plot(gc)
428    dev.off()
429
430 This produces a file called ``Rplots.pdf`` with the following
431 content. You can find more visualization examples `online
432 <http://simgrid.gforge.inria.fr/contrib/R_visualization.html>`_.
433
434 .. image:: /tuto_smpi/img/lu.S.4.png
435    :align: center
436
437 Lab 2: Tracing and Replay of LU
438 -------------------------------
439
440 Now compile and execute the LU benchmark, class A, with 32 nodes.
441
442 .. code-block:: shell
443
444    $ make lu NPROCS=32 CLASS=A
445
446 This takes several minutes to to simulate, because all code from all
447 processes has to be really executed, and everything is serialized.
448
449 SMPI provides several methods to speed things up. One of them is to
450 capture a time independent trace of the running application, and
451 replay it on a different platform with the same amount of nodes. The
452 replay is much faster than live simulation, as the computations are
453 skipped (the application must be network-dependent for this to work).
454
455 You can even generate the trace during as live simulation, as follows:
456
457 .. code-block:: shell
458
459    $ smpirun -trace-ti --cfg=tracing/filename:LU.A.32 -np 32 -platform ../cluster_backbone.xml bin/lu.A.32 
460
461 The produced trace is composed of a file ``LU.A.32`` and a folder
462 ``LU.A.32_files``. To replay this with SMPI, you need to first compile
463 the provided ``smpi_replay.cpp`` file, that comes from
464 `simgrid/examples/smpi/replay
465 <https://framagit.org/simgrid/simgrid/tree/master/examples/smpi/replay>`_.
466
467 .. code-block:: shell
468
469    $ smpicxx ../replay.cpp -O3 -o ../smpi_replay
470
471 Afterward, you can replay your trace in SMPI as follows:
472
473    $ smpirun -np 32 -platform ../cluster_torus.xml -ext smpi_replay ../smpi_replay LU.A.32
474
475 All the outputs are gone, as the application is not really simulated
476 here. Its trace is simply replayed. But if you visualize the live
477 simulation and the replay, you will see that the behavior is
478 unchanged. The simulation does not run much faster on this very
479 example, but this becomes very interesting when your application
480 is computationally hungry.
481
482 .. todo:: smpi_replay should be installed by SimGrid, and smpirun interface could be simplified here.
483
484 Lab 3: Execution Sampling on EP
485 -------------------------------
486
487 The second method to speed up simulations is to sample the computation
488 parts in the code.  This means that the person doing the simulation
489 needs to know the application and identify parts that are compute
490 intensive and take time, while being regular enough not to ruin
491 simulation accuracy. Furthermore there should not be any MPI calls
492 inside such parts of the code.
493
494 Use the EP benchmark, class B, 16 processes.
495
496 .. todo:: write this section, and the following ones.
497
498 Further Readings
499 ----------------
500
501 You may also be interested in the `SMPI reference article
502 <https://hal.inria.fr/hal-01415484>`_ or these `introductory slides
503 <http://simgrid.org/tutorials/simgrid-smpi-101.pdf>`_. The `SMPI
504 reference documentation <SMPI_doc>`_ covers much more content than
505 this short tutorial.
506
507 Finally, we regularly use SimGrid in our teachings on MPI. This way,
508 our student can experiment with platforms that they do not have access
509 to, and the associated visualisation tools helps them to understand
510 their work.  The whole material is available online, in a separate
511 project: the `SMPI CourseWare <https://simgrid.github.io/SMPI_CourseWare/>`_.
512
513 ..  LocalWords:  SimGrid