Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Another example gets documented (+cosmetics)
[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 .. _understanding_cm02:
122
123 CM02
124 ====
125
126 This is a simple model of TCP performance, where the sender stops sending packets when its TCP window is full. If the
127 acknowledgment packets are returned in time to the sender, the TCP window has no impact on the performance that then is
128 only limited by the link bandwidth. Otherwise, late acknowledgments will reduce the bandwidth.
129
130 SimGrid models this mechanism as follows: :math:`real\_BW = min(physical\_BW, \frac{TCP\_GAMMA}{2\times latency})` The used
131 bandwidth is either the physical bandwidth that is configured in the platform, or a value representing the bandwidth
132 limit due to late acknowledgments. This value is the maximal TCP window size (noted TCP Gamma in SimGrid) over the
133 round-trip time (i.e. twice the one-way latency). The default value of TCP Gamma is 4194304. This can be changed with
134 the :ref:`network/TCP-gamma <cfg=network/TCP-gamma>` configuration item.
135
136 If you want to disable this mechanism altogether (to model e.g. UDP or memory movements), you should set TCP-gamma
137 to 0. Otherwise, the time it takes to send 10 Gib of data over a 10 Gib/s link that is otherwise unused is computed as
138 follows. This is always given by :math:`latency + \frac{size}{bandwidth}`, but the bandwidth to use may be the physical
139 one (10Gb/s) or the one induced by the TCP window, depending on the latency.
140
141  - If the link latency is 0, the communication obviously takes one second.
142  - If the link latency is 0.00001s, :math:`\frac{gamma}{2\times lat}=209,715,200,000 \approx 209Gib/s` which is larger than the
143    physical bandwidth. So the physical bandwidth is used (you fully use the link) and the communication takes 1.00001s
144  - If the link latency is 0.001s, :math:`\frac{gamma}{2\times lat}=2,097,152,000 \approx 2Gib/s`, which is smalled than the
145    physical bandwidth. The communication thus fails to fully use the link, and takes about 4.77s.
146  - With a link latency of 0.1s, :math:`gamma/2\times lat \approx 21Mb/s`, so the communication takes about 476.84 + 0.1 seconds!
147  - More cases are tested and enforced by the test ``teshsuite/models/cm02-tcpgamma/cm02-tcpgamma.tesh``
148
149 For more details, please refer to "A Network Model for Simulation of Grid Application" by Henri Casanova and Loris
150 Marchal (published in 2002, thus the model name).
151
152 .. _understanding_lv08:
153
154 LV08 (default)
155 ==============
156
157 This model builds upon CM02 to model TCP windowing. It also introduces corrections factors for further realism. Lets
158 consider the following platform:
159
160 .. code-block:: xml
161
162    <host id="A" speed="1Gf" />
163    <host id="B" speed="1Gf" />
164
165    <link id="link1" latency="10ms" bandwidth="1Mbps" />
166
167    <route src="A" dst="B">
168      <link_ctn id="link1" />
169    </route>
170
171 If host `A` sends ``100kB`` (a hundred kilobytes) to host `B`, one can expect that this communication would take `0.81`
172 seconds to complete according to a simple latency-plus-size-divided-by-bandwidth model (0.01 + 8e5/1e6 = 0.81) since the
173 latency is small enough to ensure that the physical bandwidth is used (see the discussion on CM02 above). However, the
174 LV08 model is more complex to account for three phenomena that directly impact the simulation time:
175
176   - The size of a message at the application level (i.e., 100kB in this example) is not the size that is actually
177     transferred over the network. To mimic the fact that TCP and IP headers are added to each packet of the original
178     payload, the TCP model of SimGrid empirically considers that `only 97% of the nominal bandwidth` are available. In
179     other words, the size of your message is increased by a few percents, whatever this size be.
180
181   - In the real world, the TCP protocol is not able to fully exploit the bandwidth of a link from the emission of the
182     first packet. To reflect this `slow start` phenomenon, the latency declared in the platform file is multiplied by
183     `a factor of 13.01`. Here again, this is an empirically determined value that may not correspond to every TCP
184     implementations on every networks. It can be tuned when more realistic simulated times for the transfer of short
185     messages are needed though.
186
187   - When data is transferred from A to B, some TCP ACK messages travel in the opposite direction. To reflect the impact
188     of this `cross-traffic`, SimGrid simulates a flow from B to A that represents an additional bandwidth consumption
189     of `0.05%`. The route from B to A is implicitly declared in the platform file and uses the same link `link1` as if
190     the two hosts were connected through a communication bus. The bandwidth share allocated to a data transfer from A
191     to B is then the available bandwidth of `link1` (i.e., 97% of the nominal bandwidth of 1Mb/s) divided by 1.05
192     (i.e., the total consumption). This feature, activated by default, can be disabled by adding the
193     ``--cfg=network/crosstraffic:0`` flag to the command line.
194
195 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
196 seconds but
197
198 .. code-block:: python
199
200     0.01 * 13.01 + 800000 / ((0.97 * 1e6) / 1.05) =  0.996079 seconds.
201
202 For more details, please refer to "Accuracy study and improvement of network simulation in the SimGrid framework" by
203 Arnaud Legrand and Pedro Velho.
204
205 .. _models_l07:
206
207 Parallel tasks (L07)
208 ********************
209
210 This model is rather distinct from the other LMM models because it uses another objective function called *bottleneck*.
211 This is because this model is intended to be used for parallel tasks that are actions mixing flops and bytes while the
212 Max-Min objective function requires that all variables are expressed using the same unit. This is also why in reality,
213 we have one LMM system per resource kind in the simulation, but the idea remains similar.
214
215 Use the :ref:`relevant configuration <options_model_select>` to select this model in your simulation.
216
217 .. _models_wifi:
218
219 WiFi zones
220 **********
221
222 In SimGrid, WiFi networks are modeled with WiFi zones, where a zone contains the access point of the WiFi network and
223 the hosts connected to it (called `stations` in the WiFi world). The network inside a WiFi zone is modeled by declaring
224 a single regular link with a specific attribute. This link is then added to the routes to and from the stations within
225 this WiFi zone. The main difference of WiFi networks is that their performance is not determined by some link bandwidth
226 and latency but by both the access point WiFi characteristics and the distance between that access point and a given
227 station.
228
229 Such WiFi zones can be used with the LMM-based model or ns-3, and are supposed to behave similarly in both cases.
230
231 Declaring a WiFi zone
232 =====================
233
234 To declare a new WiFi network, simply declare a network zone with the ``WIFI`` routing attribute.
235
236 .. code-block:: xml
237
238         <zone id="SSID_1" routing="WIFI">
239
240 Inside this zone you must declare which host or router will be the access point of the WiFi network.
241
242 .. code-block:: xml
243
244         <prop id="access_point" value="alice"/>
245
246 Then simply declare the stations (hosts) and routers inside the WiFi network. Remember that one must have the same name
247 as the "access point" property.
248
249 .. code-block:: xml
250
251         <router id="alice" speed="1Gf"/>
252         <host id="STA0-0" speed="1Gf"/>
253         <host id="STA0-1" speed="1Gf"/>
254
255 Finally, close the WiFi zone.
256
257 .. code-block:: xml
258
259         </zone>
260
261 The WiFi zone may be connected to another zone using a traditional link and a zoneRoute. Note that the connection between two
262 zones is always wired.
263
264 .. code-block:: xml
265
266         <link id="wireline" bandwidth="100Mbps" latency="2ms" sharing_policy="SHARED"/>
267
268         <zoneRoute src="SSID_1" dst="SSID_2" gw_src="alice" gw_dst="bob">
269             <link_ctn id="wireline"/>
270         </zoneRoute>
271
272 WiFi network performance
273 ========================
274
275 The performance of a wifi network is controlled by the three following properties:
276
277  * ``mcs`` (`Modulation and Coding Scheme <https://en.wikipedia.org/wiki/Link_adaptation>`_)
278    is a property of the WiFi zone. Roughly speaking, it defines the speed at which the access point is exchanging data
279    with all the stations. It depends on the access point's model and configuration. Possible values for the MCS can be
280    found on Wikipedia for example.
281    |br| By default, ``mcs=3``.
282  * ``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
283    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>`_).
284    |br| By default, ``nss=1``.
285  * ``wifi_distance`` is the distance from a station to the access point. Each station can have its own specific value.
286    It is thus a property of the stations declared inside the WiFi zone.
287    |br| By default, ``wifi_distance=10``.
288
289 Here is an example of a zone with non-default ``mcs`` and ``nss`` values.
290
291 .. code-block:: xml
292
293         <zone id="SSID_1" routing="WIFI">
294             <prop id="access_point" value="alice"/>
295             <prop id="mcs" value="2"/>
296             <prop id="nss" value="2"/>
297         ...
298         </zone>
299
300 Here is an example of setting the ``wifi_distance`` of a given station.
301
302 .. code-block:: xml
303
304         <host id="STA0-0" speed="1Gf">
305             <prop id="wifi_distance" value="37"/>
306         </host>
307
308 Constant-time model
309 *******************
310
311 This simplistic network model is one of the few SimGrid network model that is not based on the LMM solver. In this
312 model, all communication take a constant time (one second by default). It provides the lowest level of realism, but is
313 marginally faster and much simpler to understand. This model may reveal interesting if you plan to study abstract
314 distributed algorithms such as leader election or causal broadcast.
315
316 .. _models_ns3:
317
318 ns-3 as a SimGrid model
319 ***********************
320
321 The **ns-3 based model** is the most accurate network model that you can get in SimGrid. It relies on the well-known
322 `ns-3 packet-level network simulator <http://www.nsnam.org>`_ to compute every timing information related to the network
323 transfers of your simulation. For instance, this may be used to investigate the validity of a simulation. Note that this
324 model is much slower than the LMM-based models, because ns-3 simulates the movement of every network packet involved in
325 every communication while SimGrid only recomputes the respective instantaneous speeds of the currently ongoing
326 communications when one communication starts or stops.
327
328 You need to install ns-3 and recompile SimGrid accordingly to use this model.
329
330 The SimGrid/ns-3 binding only contains features that are common to both systems. Not all ns-3 models are available from
331 SimGrid (only the TCP and WiFi ones are), while not all SimGrid platform files can be used in conjunction with ns-3
332 (routes must be of length 1). Also, the platform built in ns-3 from the SimGrid
333 description is very basic. Finally, communicating from a host to
334 itself is forbidden in ns-3, so every such communication completes
335 immediately upon startup.
336
337
338 Compiling the ns-3/SimGrid binding
339 ==================================
340
341 Installing ns-3
342 ---------------
343
344 SimGrid requires ns-3 version 3.26 or higher, and you probably want the most
345 recent version of both SimGrid and ns-3. While the Debian package of SimGrid
346 does not have the ns-3 bindings activated, you can still use the packaged version
347 of ns-3 by grabbing the ``libns3-dev ns3`` packages. Alternatively, you can
348 install ns-3 from scratch (see the `ns-3 documentation <http://www.nsnam.org>`_).
349
350 Enabling ns-3 in SimGrid
351 ------------------------
352
353 SimGrid must be recompiled with the ``enable_ns3`` option activated in cmake.
354 Optionally, use ``NS3_HINT`` to tell cmake where ns3 is installed on
355 your disk.
356
357 .. code-block:: console
358
359    $ cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed
360
361 By the end of the configuration, cmake reports whether ns-3 was found,
362 and this information is also available in ``include/simgrid/config.h``
363 If your local copy defines the variable ``SIMGRID_HAVE_NS3`` to 1, then ns-3
364 was correctly detected. Otherwise, explore ``CMakeFiles/CMakeOutput.log`` and
365 ``CMakeFiles/CMakeError.log`` to diagnose the problem.
366
367 Test that ns-3 was successfully integrated with the following command (executed from your SimGrid
368 build directory). It will run all SimGrid tests that are related to the ns-3
369 integration. If no test is run at all, then ns-3 is disabled in cmake.
370
371 .. code-block:: console
372
373    $ ctest -R ns3
374
375 Troubleshooting
376 ---------------
377
378 If you use a version of ns-3 that is not known to SimGrid yet, edit
379 ``tools/cmake/Modules/FindNS3.cmake`` in your SimGrid tree, according to the
380 comments on top of this file. Conversely, if something goes wrong with an old
381 version of either SimGrid or ns-3, try upgrading everything.
382
383 Note that there is a known bug with the version 3.31 of ns3 when it is built with
384 MPI support, like it is with the libns3-dev package in Debian 11 « Bullseye ».
385 A simple workaround is to edit the file
386 ``/usr/include/ns3.31/ns3/point-to-point-helper.h`` to remove the ``#ifdef NS3_MPI``
387 include guard.  This can be achieved with the following command (as root):
388
389 .. code-block:: console
390
391    # sed -i '/^#ifdef NS3_MPI/,+2s,^#,//&,' /usr/include/ns3.31/ns3/point-to-point-helper.h
392
393 .. _ns3_use:
394
395 Using ns-3 from SimGrid
396 =======================
397
398 Platform files compatibility
399 ----------------------------
400
401 Any route longer than one will be ignored when using ns-3. They are
402 harmless, but you still need to connect your hosts using one-hop routes.
403 The best solution is to add routers to split your route. Here is an
404 example of an invalid platform:
405
406 .. code-block:: xml
407
408    <?xml version='1.0'?>
409    <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
410    <platform version="4.1">
411      <zone id="zone0" routing="Floyd">
412        <host id="alice" speed="1Gf" />
413        <host id="bob"   speed="1Gf" />
414
415        <link id="l1" bandwidth="1Mbps" latency="5ms" />
416        <link id="l2" bandwidth="1Mbps" latency="5ms" />
417
418        <route src="alice" dst="bob">
419          <link_ctn id="l1"/>            <!-- !!!! IGNORED WHEN USED WITH ns-3       !!!! -->
420          <link_ctn id="l2"/>            <!-- !!!! ROUTES MUST CONTAIN ONE LINK ONLY !!!! -->
421        </route>
422      </zone>
423    </platform>
424
425 This can be reformulated as follows to make it usable with the ns-3 binding.
426 There is no direct connection from alice to bob, but that's OK because ns-3
427 automatically routes from point to point (using
428 ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``).
429
430 .. code-block:: xml
431
432    <?xml version='1.0'?>
433    <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
434    <platform version="4.1">
435      <zone id="zone0" routing="Full">
436        <host id="alice" speed="1Gf" />
437        <host id="bob"   speed="1Gf" />
438
439        <router id="r1" /> <!-- routers are compute-less hosts -->
440
441        <link id="l1" bandwidth="1Mbps" latency="5ms"/>
442        <link id="l2" bandwidth="1Mbps" latency="5ms"/>
443
444        <route src="alice" dst="r1">
445          <link_ctn id="l1"/>
446        </route>
447
448        <route src="r1" dst="bob">
449          <link_ctn id="l2"/>
450        </route>
451      </zone>
452    </platform>
453
454 Once your platform is OK, just change the :ref:`network/model
455 <options_model_select>` configuration option to `ns-3` as follows. The other
456 options can be used as usual.
457
458 .. code-block:: console
459
460    $ ./network-ns3 --cfg=network/model:ns-3 (other parameters)
461
462 Many other files from the ``examples/platform`` directory are usable with the
463 ns-3 model, such as `examples/platforms/dogbone.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/dogbone.xml>`_.
464 Check the file  `examples/cpp/network-ns3/network-ns3.tesh <https://framagit.org/simgrid/simgrid/tree/master/examples/cpp/network-ns3/network-ns3.tesh>`_
465 to see which ones are used in our regression tests.
466
467 Alternatively, you can manually modify the ns-3 settings by retrieving
468 the ns-3 node from any given host with the
469 :cpp:func:`simgrid::get_ns3node_from_sghost` function (defined in
470 ``simgrid/plugins/ns3.hpp``).
471
472 .. doxygenfunction:: simgrid::get_ns3node_from_sghost
473
474 Random seed
475 -----------
476 It is possible to define a fixed or random seed to the ns3 random number generator using the config tag.
477
478 .. code-block:: xml
479
480         <?xml version='1.0'?><!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
481         <platform version="4.1">
482             <config>
483                     <prop id = "network/model" value = "ns-3" />
484                     <prop id = "ns3/seed" value = "time" />
485             </config>
486         ...
487         </platform>
488
489 The first property defines that this platform will be used with the ns3 model.
490 The second property defines the seed that will be used. Defined to ``time``,
491 it will use a random seed, defined to a number it will use this number as
492 the seed.
493
494 Limitations
495 ===========
496
497 A ns-3 platform is automatically created from the provided SimGrid
498 platform. However, there are some known caveats:
499
500   * The default values (e.g., TCP parameters) are the ns-3 default values.
501   * ns-3 networks are routed using the shortest path algorithm, using ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``.
502   * End hosts cannot have more than one interface card. So, your SimGrid hosts
503     should be connected to the platform through only one link. Otherwise, your
504     SimGrid host will be considered as a router (FIXME: is it still true?).
505
506 Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully readable)
507 as possible. If the current state does not fit your needs, you should modify
508 this plugin, and/or create your own plugin from the existing one. If you come up
509 with interesting improvements, please contribute them back.
510
511 Troubleshooting
512 ===============
513
514 If your simulation hangs in a communication, this is probably because one host
515 is sending data that is not routable in your platform. Make sure that you only
516 use routes of length 1, and that any host is connected to the platform.
517 Arguably, SimGrid could detect this situation and report it, but unfortunately,
518 this still has to be done.
519
520 FMI-based models
521 ****************
522
523 `FMI <https://fmi-standard.org/>`_ is a standard to exchange models between simulators. If you want to plug such a model
524 into SimGrid, you need the `SimGrid-FMI external plugin <https://framagit.org/simgrid/simgrid-FMI>`_.
525 There is a specific `documentation <https://simgrid.frama.io/simgrid-FMI/index.html>`_ available for the plugin.
526 This was used to accurately study a *Smart grid* through co-simulation: `PandaPower <http://www.pandapower.org/>`_ was
527 used to simulate the power grid, `ns-3 <https://nsnam.org/>`_ was used to simulate the communication network while SimGrid was
528 used to simulate the IT infrastructure. Please also refer to the `relevant publication <https://hal.science/hal-03217562>`_
529 for more details.
530
531 .. _models_other:
532
533 Other kind of models
534 ********************
535
536 As for any simulator, models are very important components of the SimGrid toolkit. Several kind of models are used in
537 SimGrid beyond the performance models described above:
538
539 The **routing models** constitute advanced elements of the platform description. This description naturally entails
540 :ref:`components<platform>` that are very related to the performance models. For instance, determining the execution
541 time of a task obviously depends on the characteristics of the machine that executes this task. Furthermore, networking
542 zones can be interconnected to compose larger platforms `in a scalable way <http://hal.inria.fr/hal-00650233/>`_. Each
543 of these zones can be given a specific :ref:`routing model<platform_routing>` that efficiently computes the list of
544 links forming a network path between two given hosts.
545
546 The model checker uses an abstraction of the performance simulations. Mc SimGrid explores every causally possible
547 execution paths of the application, completely abstracting the performance away. The simulated time is not even
548 computed in this mode! The abstraction involved in this process also models the mutual impacts among actions, to not
549 re-explore histories that only differ by the order of independent and unrelated actions. As with the rest of the model
550 checker, these models are unfortunately still to be documented properly.
551
552
553 .. |br| raw:: html
554
555    <br />