Logo AND Algorithmique Numérique Distribuée

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