Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Merge branch 'master' into 'master'
[simgrid.git] / docs / source / Models.rst
1 .. raw:: html
2
3    <object id="TOC" data="graphical-toc.svg" type="image/svg+xml"></object>
4    <script>
5    window.onload=function() { // Wait for the SVG to be loaded before changing it
6      var elem=document.querySelector("#TOC").contentDocument.getElementById("ModelBox")
7      elem.style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1;stroke:#000000;stroke-width:0.35277778;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1";
8    }
9    </script>
10    <br/>
11    <br/>
12
13 .. _models:
14
15 The SimGrid Models
16 ##################
17
18 This page focuses on the **performance models** that compute the duration of :ref:`every activities <S4U_main_concepts>`
19 in the simulator depending on the platform characteristics and on the other activities that are currently sharing the
20 resources. If you look for other kind of models (such as routing models or compute model), please refer to :ref:`the
21 bottom of this page <models_other>`.
22
23 Modeled resources
24 *****************
25
26 The main objective of SimGrid is to provide timing information for three following kind of resources: network, CPU,
27 and disk.
28
29 The **network models** have been improved and regularly assessed for almost 20 years. It should be possible to get
30 accurate predictions once you properly :ref:`calibrate the models for your settings<models_calibration>`. As detailed
31 in the next sections, SimGrid provides several network models. Two plugins can also be used to compute the network
32 energy consumption: One for the :ref:`wired networks<plugin_link_energy>`, and another one for the :ref:`Wi-Fi networks
33 <plugin_link_energy>`. Some users find :ref:`TCP simulated performance counter-intuitive<understanding_lv08>` at first
34 in SimGrid, sometimes because of a misunderstanding of the TCP behavior in real networks.
35
36 The **computing models** are less developed in SimGrid. Through the S4U interface, the user specifies the amount of
37 computational work (expressed in FLOPs, for floating point operations) that each computation "consumes", and the model
38 simply divides this amount by the host's FLOP rate to compute the duration of this execution. In SMPI, the user code
39 is automatically timed, and the :ref:`computing speed<cfg=smpi/host-speed>` of the host machine is used to evaluate
40 the corresponding amount of FLOPs. This model should be sufficient for most users, even though assuming a constant FLOP
41 rate for each machine remains a crude simplification. In reality, the flops rate varies because of I/O, memory, and
42 cache effects. It is somehow possible to :ref:`overcome this simplification<cfg=smpi/comp-adjustment-file>`, but the
43 required calibration process is rather intricate and not documented yet (feel free to
44 :ref:`contact the community<community>` on need).
45 In the future, more advanced models may be added but the existing model proved good enough for all experiments done on
46 distributed applications during the last two decades. The CPU energy consumption can be computed with the
47 :ref:`relevant plugin<plugin_host_energy>`.
48
49 The **disk models** of SimGrid are more recent than those for the network and computing resources, but they should
50 still be correct for most users. `Studies have shown <https://hal.inria.fr/hal-01197128>`_ that they are sensitive
51 under some conditions, and a :ref:`calibration process<howto_disk>` is provided. As usual, you probably want to
52 double-check their predictions through an appropriate validation campaign.
53
54 LMM-based Models
55 ****************
56
57 SimGrid aims at the sweet spot between accuracy and simulation speed. About accuracy, our goal is to report correct
58 performance trends when comparing competing designs with a minimal burden on the user, while allowing power users to
59 fine tune the simulation models for predictions that are within 5% or less of the results on real machines. For
60 example, we determined the `speedup achieved by the Tibidabo ARM-based cluster <http://hal.inria.fr/hal-00919507>`_
61 before it was even built. About simulation speed, the tool must be fast and scalable enough to study modern IT systems
62 at scale. SimGrid was for example used to simulate `a Chord ring involving millions of actors
63 <https://hal.inria.fr/inria-00602216>`_ (even though that has not really been more instructive than smaller scale
64 simulations for this protocol), or `a qualification run at full-scale of the Stampede supercomputer
65 <https://hal.inria.fr/hal-02096571>`_.
66
67 Most of our models are based on a linear max-min solver (LMM), as depicted below. The actors' activities are
68 represented by actions in the simulation kernel, accounting for both the initial amount of work of the corresponding
69 activity (in FLOPs for computing activities or bytes for networking and disk activities), and the currently remaining
70 amount of work to process.
71
72 At each simulation step, the instantaneous computing and communicating capacity of each action is computed according
73 to the model. A set of constraints is used to express for example that the accumulated instantaneous consumption of a
74 given resource by a set actions must remain smaller than the nominal capacity speed of that resource. In the example
75 below, it is stated that the speed :math:`\varrho_1` of activity 1 plus the speed :math:`\varrho_n`
76 of activity :math:`n` must remain smaller than the capacity :math:`C_A` of the corresponding host A.
77
78 .. image:: img/lmm-overview.svg
79
80 There are obviously many valuations of :math:`\varrho_1, \ldots{}, \varrho_n` that respect such as set of constraints.
81 SimGrid usually computes the instantaneous speeds according to a Max-Min objective function, that is maximizing the
82 minimum over all :math:`\varrho_i`. The coefficients associated to each variable in the inequalities are used to model
83 some performance effects, such as the fact that TCP tends to favor communications with small RTTs. These coefficients
84 are computed from both hard-coded values and :ref:`latency and bandwidth factors<cfg=network/latency-factor>` (more
85 details on network performance modeling is given in the next section).
86
87 Once the instantaneous speeds are computed, the simulation kernel determines what is the earliest terminating action
88 from their respective speeds and remaining amounts of work. The simulated time is then updated along with the values
89 in the LMM. As some actions have nothing left to do, the corresponding activities thus terminate, which in turn
90 unblocks the corresponding actors that can further execute.
91
92 Most of the SimGrid models build upon the LMM solver, that they adapt and configure for their respective usage. For CPU
93 and disk activities, the LMM-based models are respectively named **Cas01** and **S19**. The existing network models are
94 described in the next section.
95
96 The TCP models
97 **************
98
99 SimGrid provides several network performance models which compute the time taken by each communication in isolation.
100 **CM02** is the simplest one. It captures TCP windowing effects, but does not introduce any correction factors. This
101 model should be used if you prefer understandable results over realistic ones. **LV08** (the default model) uses
102 constant factors that are intended to capture common effects such as slow-start, the fact that TCP headers reduce the
103 *effective* bandwidth, or TCP's ACK messages. **SMPI** uses more advanced factors that also capture the MPI-specific
104 effects such as the switch between the eager vs. rendez-vous communication modes. You can :ref:`choose the
105 model<options_model_select>` on command line, and these models can be :ref:`further configured<options_model>`.
106
107 The LMM solver is then used as described above to compute the effect of contention on the communication time that is
108 computed by the TCP model. For sake of realism, the sharing on saturated links is not necessarily a fair sharing.
109 Instead, flows receive an amount of bandwidth inversely proportional to their round trip time.
110
111 Regardless of the used TCP model, the latency is paid beforehand. It is as if the communication only starts after a
112 little delay corresponding to the latency. During that time, the communication has no impact on the links (the other
113 communications are not slowed down, because there is no contention yet).
114
115 In addition to these LMM-based models, you can use the :ref:`ns-3 simulator as a network model <models_ns3>`. It is much
116 more detailed than the pure SimGrid models and thus slower, but it is easier to get more accurate results. Concerning
117 the speed, both simulators are linear in the size of their input, but ns-3 has a much larger input in case of large
118 steady communications. On the other hand, the SimGrid models must be carefully :ref:`calibrated <models_calibration>` if
119 accuracy is really important to your study, while ns-3 models are less demanding with that regard.
120
121 CM02
122 ====
123
124 This is a simple model of TCP performance, where the sender stops sending packets when its TCP window is full. If the
125 acknowledgment packets are returned in time to the sender, the TCP window has no impact on the performance that then is
126 only limited by the link bandwidth. Otherwise, late acknowledgments will reduce the bandwidth.
127
128 SimGrid models this mechanism as follows: :math:`realBW = min(physicalBW, \frac{TCP_GAMMA}{2\times latency})` The used
129 bandwidth is either the physical bandwidth that is configured in the platform, or a value representing the bandwidth
130 limit due to late acknowledgments. This value is the maximal TCP window size (noted TCP Gamma in SimGrid) over the
131 round-trip time (i.e. twice the one-way latency). The default value of TCP Gamma is 4194304. This can be changed with
132 the :ref:`network/TCP-gamma <cfg=network/TCP-gamma>` configuration item.
133
134 Let's compute the time it takes to send 10 Gb of data over a 10 Gb/s link that is otherwise unused. This is always given
135 by :math:`latency + size / bandwidth`, but the bandwidth to use may be the physical one (10Gb/s) or the one induced by
136 the TCP window, depending on the latency.
137
138  - If the link latency is 0, it obviously takes one second.
139  - If the link latency is 0.00001s, :math:`gamma/2\times lat=209,715,200,000 \approx 209Gb/s` which is larger than the
140    physical bandwidth. So the physical bandwidth is used (you fully use the link) and the communication takes 1.00001s
141  - If the link latency is 0.001s, :math:`gamma/2\times lat=2,097,152,000 \approx 2Gb/s`, which is smalled than the
142    physical bandwidth. The communication thus fails to fully use the link, and takes 5.12s.
143  - With a link latency of 0.1s, :math:`gamma/2\times lat \approx 21Mb/s`, so the communication takes 512 seconds!
144
145 For more details, please refer to "A Network Model for Simulation of Grid Application" by Henri Casanova and Loris
146 Marchal (published in 2002, thus the model name).
147
148 .. _understanding_lv08:
149
150 LV08 (default)
151 ==============
152
153 This model builds upon CM02 to model TCP windowing. It also introduces corrections factors for further realism. Lets
154 consider the following platform:
155
156 .. code-block:: xml
157
158    <host id="A" speed="1Gf" />
159    <host id="B" speed="1Gf" />
160
161    <link id="link1" latency="10ms" bandwidth="1Mbps" />
162
163    <route src="A" dst="B">
164      <link_ctn id="link1" />
165    </route>
166
167 If host `A` sends ``100kB`` (a hundred kilobytes) to host `B`, one can expect that this communication would take `0.81`
168 seconds to complete according to a simple latency-plus-size-divided-by-bandwidth model (0.01 + 8e5/1e6 = 0.81) since the
169 latency is small enough to ensure that the physical bandwidth is used (see the discussion on CM02 above). However, the
170 LV08 model is more complex to account for three phenomena that directly impact the simulation time:
171
172   - The size of a message at the application level (i.e., 100kB in this example) is not the size that is actually
173     transferred over the network. To mimic the fact that TCP and IP headers are added to each packet of the original
174     payload, the TCP model of SimGrid empirically considers that `only 97% of the nominal bandwidth` are available. In
175     other words, the size of your message is increased by a few percents, whatever this size be.
176
177   - In the real world, the TCP protocol is not able to fully exploit the bandwidth of a link from the emission of the
178     first packet. To reflect this `slow start` phenomenon, the latency declared in the platform file is multiplied by
179     `a factor of 13.01`. Here again, this is an empirically determined value that may not correspond to every TCP
180     implementations on every networks. It can be tuned when more realistic simulated times for the transfer of short
181     messages are needed though.
182
183   - When data is transferred from A to B, some TCP ACK messages travel in the opposite direction. To reflect the impact
184     of this `cross-traffic`, SimGrid simulates a flow from B to A that represents an additional bandwidth consumption
185     of `0.05%`. The route from B to A is implicitly declared in the platform file and uses the same link `link1` as if
186     the two hosts were connected through a communication bus. The bandwidth share allocated to a data transfer from A
187     to B is then the available bandwidth of `link1` (i.e., 97% of the nominal bandwidth of 1Mb/s) divided by 1.05
188     (i.e., the total consumption). This feature, activated by default, can be disabled by adding the
189     ``--cfg=network/crosstraffic:0`` flag to the command line.
190
191 As a consequence, the time to transfer 100kB from A to B as simulated by the default TCP model of SimGrid is not 0.81
192 seconds but
193
194 .. code-block:: python
195
196     0.01 * 13.01 + 800000 / ((0.97 * 1e6) / 1.05) =  0.996079 seconds.
197
198 For more details, please refer to "Accuracy study and improvement of network simulation in the SimGrid framework" by
199 Arnaud Legrand and Pedro Velho.
200
201 Parallel tasks (L07)
202 ********************
203
204 This model is rather distinct from the other LMM models because it uses another objective function called *bottleneck*.
205 This is because this model is intended to be used for parallel tasks that are actions mixing flops and bytes while the
206 Max-Min objective function requires that all variables are expressed using the same unit. This is also why in reality,
207 we have one LMM system per resource kind in the simulation, but the idea remains similar.
208
209 .. _models_wifi:
210
211 WiFi zones
212 **********
213
214 In SimGrid, WiFi networks are modeled with WiFi zones, where a zone contains the access point of the WiFi network and
215 the hosts connected to it (called `stations` in the WiFi world). The network inside a WiFi zone is modeled by declaring
216 a single regular link with a specific attribute. This link is then added to the routes to and from the stations within
217 this WiFi zone. The main difference of WiFi networks is that their performance is not determined by some link bandwidth
218 and latency but by both the access point WiFi characteristics and the distance between that access point and a given
219 station.
220
221 Such WiFi zones can be used with the LMM-based model or ns-3, and are supposed to behave similarly in both cases.
222
223 Declaring a WiFi zone
224 =====================
225
226 To declare a new WiFi network, simply declare a network zone with the ``WIFI`` routing attribute.
227
228 .. code-block:: xml
229
230         <zone id="SSID_1" routing="WIFI">
231
232 Inside this zone you must declare which host or router will be the access point of the WiFi network.
233
234 .. code-block:: xml
235
236         <prop id="access_point" value="alice"/>
237
238 Then simply declare the stations (hosts) and routers inside the WiFi network. Remember that one must have the same name
239 as the "access point" property.
240
241 .. code-block:: xml
242
243         <router id="alice" speed="1Gf"/>
244         <host id="STA0-0" speed="1Gf"/>
245         <host id="STA0-1" speed="1Gf"/>
246
247 Finally, close the WiFi zone.
248
249 .. code-block:: xml
250
251         </zone>
252
253 The WiFi zone may be connected to another zone using a traditional link and a zoneRoute. Note that the connection between two
254 zones is always wired.
255
256 .. code-block:: xml
257
258         <link id="wireline" bandwidth="100Mbps" latency="2ms" sharing_policy="SHARED"/>
259
260         <zoneRoute src="SSID_1" dst="SSID_2" gw_src="alice" gw_dst="bob">
261             <link_ctn id="wireline"/>
262         </zoneRoute>
263
264 WiFi network performance
265 ========================
266
267 The performance of a wifi network is controlled by the three following properties:
268
269  * ``mcs`` (`Modulation and Coding Scheme <https://en.wikipedia.org/wiki/Link_adaptation>`_)
270    is a property of the WiFi zone. Roughly speaking, it defines the speed at which the access point is exchanging data
271    with all the stations. It depends on the access point's model and configuration. Possible values for the MCS can be
272    found on Wikipedia for example.
273    |br| By default, ``mcs=3``.
274  * ``nss`` (Number of Spatial Streams, or `number of antennas <https://en.wikipedia.org/wiki/IEEE_802.11n-2009#Number_of_antennas>`_) is another property of the WiFi zone. It defines the amount of simultaneous data streams that the access
275    point can sustain. Not all values of MCS and NSS are valid nor compatible (cf. `802.11n standard <https://en.wikipedia.org/wiki/IEEE_802.11n-2009#Data_rates>`_).
276    |br| By default, ``nss=1``.
277  * ``wifi_distance`` is the distance from a station to the access point. Each station can have its own specific value.
278    It is thus a property of the stations declared inside the WiFi zone.
279    |br| By default, ``wifi_distance=10``.
280
281 Here is an example of a zone with non-default ``mcs`` and ``nss`` values.
282
283 .. code-block:: xml
284
285         <zone id="SSID_1" routing="WIFI">
286             <prop id="access_point" value="alice"/>
287             <prop id="mcs" value="2"/>
288             <prop id="nss" value="2"/>
289         ...
290         </zone>
291
292 Here is an example of setting the ``wifi_distance`` of a given station.
293
294 .. code-block:: xml
295
296         <host id="STA0-0" speed="1Gf">
297             <prop id="wifi_distance" value="37"/>
298         </host>
299
300 Constant-time model
301 *******************
302
303 This simplistic network model is one of the few SimGrid network model that is not based on the LMM solver. In this
304 model, all communication take a constant time (one second by default). It provides the lowest level of realism, but is
305 marginally faster and much simpler to understand. This model may reveal interesting if you plan to study abstract
306 distributed algorithms such as leader election or causal broadcast.
307
308 .. _models_ns3:
309
310 ns-3 as a SimGrid model
311 ***********************
312
313 The **ns-3 based model** is the most accurate network model that you can get in SimGrid. It relies on the well-known
314 `ns-3 packet-level network simulator <http://www.nsnam.org>`_ to compute every timing information related to the network
315 transfers of your simulation. For instance, this may be used to investigate the validity of a simulation. Note that this
316 model is much slower than the LMM-based models, because ns-3 simulates the movement of every network packet involved in
317 every communication while SimGrid only recomputes the respective instantaneous speeds of the currently ongoing
318 communications when one communication starts or stops.
319
320 You need to install ns-3 and recompile SimGrid accordingly to use this model.
321
322 The SimGrid/ns-3 binding only contains features that are common to both systems. Not all ns-3 models are available from
323 SimGrid (only the TCP and WiFi ones are), while not all SimGrid platform files can be used in conjunction with ns-3
324 (routes must be of length 1). Also, the platform built in ns-3 from the SimGrid
325 description is very basic. Finally, communicating from a host to
326 itself is forbidden in ns-3, so every such communication completes
327 immediately upon startup.
328
329
330 Compiling the ns-3/SimGrid binding
331 ==================================
332
333 Installing ns-3
334 ---------------
335
336 SimGrid requires ns-3 version 3.26 or higher, and you probably want the most
337 recent version of both SimGrid and ns-3. While the Debian package of SimGrid
338 does not have the ns-3 bindings activated, you can still use the packaged version
339 of ns-3 by grabbing the ``libns3-dev ns3`` packages. Alternatively, you can
340 install ns-3 from scratch (see the `ns-3 documentation <http://www.nsnam.org>`_).
341
342 Enabling ns-3 in SimGrid
343 ------------------------
344
345 SimGrid must be recompiled with the ``enable_ns3`` option activated in cmake.
346 Optionally, use ``NS3_HINT`` to tell cmake where ns3 is installed on
347 your disk.
348
349 .. code-block:: console
350
351    $ cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed
352
353 By the end of the configuration, cmake reports whether ns-3 was found,
354 and this information is also available in ``include/simgrid/config.h``
355 If your local copy defines the variable ``SIMGRID_HAVE_NS3`` to 1, then ns-3
356 was correctly detected. Otherwise, explore ``CMakeFiles/CMakeOutput.log`` and
357 ``CMakeFiles/CMakeError.log`` to diagnose the problem.
358
359 Test that ns-3 was successfully integrated with the following command (executed from your SimGrid
360 build directory). It will run all SimGrid tests that are related to the ns-3
361 integration. If no test is run at all, then ns-3 is disabled in cmake.
362
363 .. code-block:: console
364
365    $ ctest -R ns3
366
367 Troubleshooting
368 ---------------
369
370 If you use a version of ns-3 that is not known to SimGrid yet, edit
371 ``tools/cmake/Modules/FindNS3.cmake`` in your SimGrid tree, according to the
372 comments on top of this file. Conversely, if something goes wrong with an old
373 version of either SimGrid or ns-3, try upgrading everything.
374
375 Note that there is a known bug with the version 3.31 of ns3 when it is built with
376 MPI support, like it is with the libns3-dev package in Debian 11 « Bullseye ».
377 A simple workaround is to edit the file
378 ``/usr/include/ns3.31/ns3/point-to-point-helper.h`` to remove the ``#ifdef NS3_MPI``
379 include guard.  This can be achieved with the following command (as root):
380
381 .. code-block:: console
382
383    # sed -i '/^#ifdef NS3_MPI/,+2s,^#,//&,' /usr/include/ns3.31/ns3/point-to-point-helper.h
384
385 .. _ns3_use:
386
387 Using ns-3 from SimGrid
388 =======================
389
390 Platform files compatibility
391 ----------------------------
392
393 Any route longer than one will be ignored when using ns-3. They are
394 harmless, but you still need to connect your hosts using one-hop routes.
395 The best solution is to add routers to split your route. Here is an
396 example of an invalid platform:
397
398 .. code-block:: xml
399
400    <?xml version='1.0'?>
401    <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
402    <platform version="4.1">
403      <zone id="zone0" routing="Floyd">
404        <host id="alice" speed="1Gf" />
405        <host id="bob"   speed="1Gf" />
406
407        <link id="l1" bandwidth="1Mbps" latency="5ms" />
408        <link id="l2" bandwidth="1Mbps" latency="5ms" />
409
410        <route src="alice" dst="bob">
411          <link_ctn id="l1"/>            <!-- !!!! IGNORED WHEN USED WITH ns-3       !!!! -->
412          <link_ctn id="l2"/>            <!-- !!!! ROUTES MUST CONTAIN ONE LINK ONLY !!!! -->
413        </route>
414      </zone>
415    </platform>
416
417 This can be reformulated as follows to make it usable with the ns-3 binding.
418 There is no direct connection from alice to bob, but that's OK because ns-3
419 automatically routes from point to point (using
420 ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``).
421
422 .. code-block:: xml
423
424    <?xml version='1.0'?>
425    <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
426    <platform version="4.1">
427      <zone id="zone0" routing="Full">
428        <host id="alice" speed="1Gf" />
429        <host id="bob"   speed="1Gf" />
430
431        <router id="r1" /> <!-- routers are compute-less hosts -->
432
433        <link id="l1" bandwidth="1Mbps" latency="5ms"/>
434        <link id="l2" bandwidth="1Mbps" latency="5ms"/>
435
436        <route src="alice" dst="r1">
437          <link_ctn id="l1"/>
438        </route>
439
440        <route src="r1" dst="bob">
441          <link_ctn id="l2"/>
442        </route>
443      </zone>
444    </platform>
445
446 Once your platform is OK, just change the :ref:`network/model
447 <options_model_select>` configuration option to `ns-3` as follows. The other
448 options can be used as usual.
449
450 .. code-block:: console
451
452    $ ./network-ns3 --cfg=network/model:ns-3 (other parameters)
453
454 Many other files from the ``examples/platform`` directory are usable with the
455 ns-3 model, such as `examples/platforms/dogbone.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/dogbone.xml>`_.
456 Check the file  `examples/cpp/network-ns3/network-ns3.tesh <https://framagit.org/simgrid/simgrid/tree/master/examples/cpp/network-ns3/network-ns3.tesh>`_
457 to see which ones are used in our regression tests.
458
459 Alternatively, you can manually modify the ns-3 settings by retrieving
460 the ns-3 node from any given host with the
461 :cpp:func:`simgrid::get_ns3node_from_sghost` function (defined in
462 ``simgrid/plugins/ns3.hpp``).
463
464 .. doxygenfunction:: simgrid::get_ns3node_from_sghost
465
466 Random seed
467 -----------
468 It is possible to define a fixed or random seed to the ns3 random number generator using the config tag.
469
470 .. code-block:: xml
471
472         <?xml version='1.0'?><!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
473         <platform version="4.1">
474             <config>
475                     <prop id = "network/model" value = "ns-3" />
476                     <prop id = "ns3/seed" value = "time" />
477             </config>
478         ...
479         </platform>
480
481 The first property defines that this platform will be used with the ns3 model.
482 The second property defines the seed that will be used. Defined to ``time``,
483 it will use a random seed, defined to a number it will use this number as
484 the seed.
485
486 Limitations
487 ===========
488
489 A ns-3 platform is automatically created from the provided SimGrid
490 platform. However, there are some known caveats:
491
492   * The default values (e.g., TCP parameters) are the ns-3 default values.
493   * ns-3 networks are routed using the shortest path algorithm, using ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``.
494   * End hosts cannot have more than one interface card. So, your SimGrid hosts
495     should be connected to the platform through only one link. Otherwise, your
496     SimGrid host will be considered as a router (FIXME: is it still true?).
497
498 Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully readable)
499 as possible. If the current state does not fit your needs, you should modify
500 this plugin, and/or create your own plugin from the existing one. If you come up
501 with interesting improvements, please contribute them back.
502
503 Troubleshooting
504 ===============
505
506 If your simulation hangs in a communication, this is probably because one host
507 is sending data that is not routable in your platform. Make sure that you only
508 use routes of length 1, and that any host is connected to the platform.
509 Arguably, SimGrid could detect this situation and report it, but unfortunately,
510 this still has to be done.
511
512 FMI-based models
513 ****************
514
515 `FMI <https://fmi-standard.org/>`_ is a standard to exchange models between simulators. If you want to plug such a model 
516 into SimGrid, you need the `SimGrid-FMI external plugin <https://framagit.org/simgrid/simgrid-FMI>`_. 
517 There is a specific `documentation <https://simgrid.frama.io/simgrid-FMI/index.html>`_ available for the plugin.
518 This was used to accurately study a *Smart grid* through co-simulation: `PandaPower <http://www.pandapower.org/>`_ was 
519 used to simulate the power grid, `ns-3 <https://nsnam.org/>`_ was used to simulate the communication network while SimGrid was 
520 used to simulate the IT infrastructure. Please also refer to the `relevant publication <https://hal.science/hal-03217562>`_ 
521 for more details.
522
523 .. _models_other:
524
525 Other kind of models
526 ********************
527
528 As for any simulator, models are very important components of the SimGrid toolkit. Several kind of models are used in
529 SimGrid beyond the performance models described above:
530
531 The **routing models** constitute advanced elements of the platform description. This description naturally entails
532 :ref:`components<platform>` that are very related to the performance models. For instance, determining the execution
533 time of a task obviously depends on the characteristics of the machine that executes this task. Furthermore, networking
534 zones can be interconnected to compose larger platforms `in a scalable way <http://hal.inria.fr/hal-00650233/>`_. Each
535 of these zones can be given a specific :ref:`routing model<platform_routing>` that efficiently computes the list of
536 links forming a network path between two given hosts.
537
538 The model checker uses an abstraction of the performance simulations. Mc SimGrid explores every causally possible
539 execution paths of the application, completely abstracting the performance away. The simulated time is not even
540 computed in this mode! The abstraction involved in this process also models the mutual impacts among actions, to not
541 re-explore histories that only differ by the order of independent and unrelated actions. As with the rest of the model
542 checker, these models are unfortunately still to be documented properly.
543
544
545 .. |br| raw:: html
546
547    <br />