8 - Main existing models (contention, cste, LM07)
9 - Main concepts (Routing, LMM) + link to the papers
10 - How to switch on the command line
12 .. _understanding_lv08:
17 When simulating a data transfer between two hosts, you may be surprised
18 by the obtained simulation time. Lets consider the following platform:
22 <host id="A" speed="1Gf" />
23 <host id="B" speed="1Gf" />
25 <link id="link1" latency="10ms" bandwidth="1Mbps" />
27 <route src="A" dst="B">
28 <link_ctn id="link1" />
31 If host `A` sends `100kB` (a hundred kilobytes) to host `B`, one could expect
32 that this communication would take `0.81` seconds to complete according to a
33 simple latency-plus-size-divided-by-bandwidth model (0.01 + 8e5/1e6 = 0.81).
34 However, the default TCP model of SimGrid is a bit more complex than that. It
35 accounts for three phenomena that directly impact the simulation time even
36 on such a simple example:
38 - The size of a message at the application level (i.e., 100kB in this
39 example) is not the size that will actually be transferred over the
40 network. To mimic the fact that TCP and IP headers are added to each packet of
41 the original payload, the TCP model of SimGrid empirically considers that
42 `only 97% of the nominal bandwidth` are available. In other words, the
43 size of your message is increased by a few percents, whatever this size be.
45 - In the real world, the TCP protocol is not able to fully exploit the
46 bandwidth of a link from the emission of the first packet. To reflect this
47 `slow start` phenomenon, the latency declared in the platform file is
48 multiplied by `a factor of 13.01`. Here again, this is an empirically
49 determined value that may not correspond to every TCP implementations on
50 every networks. It can be tuned when more realistic simulated times for
51 short messages are needed though.
53 - When data is transferred from A to B, some TCP ACK messages travel in the
54 opposite direction. To reflect the impact of this `cross-traffic`, SimGrid
55 simulates a flow from B to A that represents an additional bandwidth
56 consumption of `0.05`. The route from B to A is implicitly declared in the
57 platform file and uses the same link `link1` as if the two hosts were
58 connected through a communication bus. The bandwidth share allocated to the
59 flow from A to B is then the available bandwidth of `link1` (i.e., 97% of
60 the nominal bandwidth of 1Mb/s) divided by 1.05 (i.e., the total consumption).
61 This feature, activated by default, can be disabled by adding the
62 `--cfg=network/crosstraffic:0` flag to command line.
64 As a consequence, the time to transfer 100kB from A to B as simulated by the
65 default TCP model of SimGrid is not 0.81 seconds but
67 .. code-block:: python
69 0.01 * 13.01 + 800000 / ((0.97 * 1e6) / 1.05) = 0.996079 seconds.
73 ns-3 as a SimGrid model
74 ***********************
76 You can use the well-known `ns-3 packet-level network simulator
77 <http://www.nsnam.org>`_ as a SimGrid model, for example to investigate the
78 validity of your simulation. Just install ns-3 and recompile SimGrid
81 The SimGrid/ns-3 binding only contains features that are common to both systems.
82 Not all ns-3 models are available from SimGrid (only the TCP and WiFi ones are),
83 while not all SimGrid platform files can be used in conjunction ns-3 (routes
84 must be of length 1). Also, the platform built in ns-3 from the SimGrid
85 description is very basic. Finally, communicating from a host to
86 itself is forbidden in ns-3, so every such communication completes
87 immediately upon startup.
90 Compiling the ns-3/SimGrid binding
91 ==================================
96 SimGrid requires ns-3 version 3.26 or higher, and you probably want the most
97 recent version of both SimGrid and ns-3. While the Debian package of SimGrid
98 don't have the ns-3 bindings activated, you can still use the packaged version
99 of ns-3 by grabbing the ``libns3-dev ns3`` packages. Alternatively, you can
100 install ns-3 from scratch (see the `ns-3 documentation <http://www.nsnam.org>`_).
102 Enabling ns-3 in SimGrid
103 ------------------------
105 SimGrid must be recompiled with the ``enable_ns3`` option activated in cmake.
106 Optionally, use ``NS3_HINT`` to tell cmake where ns3 is installed on
109 .. code-block:: console
111 $ cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed
113 By the end of the configuration, cmake reports whether ns-3 was found,
114 and this information is also available in ``include/simgrid/config.h``
115 If your local copy defines the variable ``SIMGRID_HAVE_NS3`` to 1, then ns-3
116 was correctly detected. Otherwise, explore ``CMakeFiles/CMakeOutput.log`` and
117 ``CMakeFiles/CMakeError.log`` to diagnose the problem.
119 Test that ns-3 was successfully integrated with the following (from your SimGrid
120 build directory). It will run all SimGrid tests that are related to the ns-3
121 integration. If no test is run at all, you probably forgot to enable ns-3 in cmake.
123 .. code-block:: console
130 If you use a version of ns-3 that is not known to SimGrid yet, edit
131 ``tools/cmake/Modules/FindNS3.cmake`` in your SimGrid tree, according to the
132 comments on top of this file. Conversely, if something goes wrong with an old
133 version of either SimGrid or ns-3, try upgrading everything.
135 Note that there is a known bug with version 3.31 of ns3, when it's built with
136 MPI support, like it is with the package libns3-dev in Debian 11 « Bullseye ».
137 A simple workaround is to edit the file
138 ``/usr/include/ns3.31/ns3/point-to-point-helper.h`` to remove the ``#ifdef NS3_MPI``
139 include guard. This can be achieved with the following command (as root):
141 .. code-block:: console
143 # sed -i '/^#ifdef NS3_MPI/,+2s,^#,//&,' /usr/include/ns3.31/ns3/point-to-point-helper.h
147 Using ns-3 from SimGrid
148 =======================
150 Platform files compatibility
151 ----------------------------
153 Any route longer than one will be ignored when using ns-3. They are
154 harmless, but you still need to connect your hosts using one-hop routes.
155 The best solution is to add routers to split your route. Here is an
156 example of an invalid platform:
160 <?xml version='1.0'?>
161 <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
162 <platform version="4.1">
163 <zone id="zone0" routing="Floyd">
164 <host id="alice" speed="1Gf" />
165 <host id="bob" speed="1Gf" />
167 <link id="l1" bandwidth="1Mbps" latency="5ms" />
168 <link id="l2" bandwidth="1Mbps" latency="5ms" />
170 <route src="alice" dst="bob">
171 <link_ctn id="l1"/> <!-- !!!! IGNORED WHEN USED WITH ns-3 !!!! -->
172 <link_ctn id="l2"/> <!-- !!!! ROUTES MUST CONTAIN ONE LINK ONLY !!!! -->
177 This can be reformulated as follows to make it usable with the ns-3 binding.
178 There is no direct connection from alice to bob, but that's OK because ns-3
179 automatically routes from point to point (using
180 ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``).
184 <?xml version='1.0'?>
185 <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
186 <platform version="4.1">
187 <zone id="zone0" routing="Full">
188 <host id="alice" speed="1Gf" />
189 <host id="bob" speed="1Gf" />
191 <router id="r1" /> <!-- routers are compute-less hosts -->
193 <link id="l1" bandwidth="1Mbps" latency="5ms"/>
194 <link id="l2" bandwidth="1Mbps" latency="5ms"/>
196 <route src="alice" dst="r1">
200 <route src="r1" dst="bob">
206 Once your platform is OK, just change the :ref:`network/model
207 <options_model_select>` configuration option to `ns-3` as follows. The other
208 options can be used as usual.
210 .. code-block:: console
212 $ ./network-ns3 --cfg=network/model:ns-3 (other parameters)
214 Many other files from the ``examples/platform`` directory are usable with the
215 ns-3 model, such as `examples/platforms/dogbone.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/dogbone.xml>`_.
216 Check the file `examples/cpp/network-ns3/network-ns3.tesh <https://framagit.org/simgrid/simgrid/tree/master/examples/cpp/network-ns3/network-ns3.tesh>`_
217 to see which ones are used in our regression tests.
219 Alternatively, you can manually modify the ns-3 settings by retrieving
220 the ns-3 node from any given host with the
221 :cpp:func:`simgrid::get_ns3node_from_sghost` function (defined in
222 ``simgrid/plugins/ns3.hpp``).
224 .. doxygenfunction:: simgrid::get_ns3node_from_sghost
230 In SimGrid, WiFi networks are modeled with WiFi zones, where a zone contains
231 the access point of the WiFi network and the hosts connected to it (called
232 station in the WiFi world). Links inside WiFi zones are modeled as regular
233 links with a specific attribute, and these links are then added to routes
234 between hosts. The main difference When using ns-3 WiFi networks is that
235 the network performance is not given by the link bandwidth and latency but
236 by the access point WiFi characteristics, and the distance between the access
239 So, to declare a new WiFi network, simply declare a zone with the ``WIFI``
244 <zone id="SSID_1" routing="WIFI">
246 Inside this zone you must declare which host or router will be the access point
251 <prop id="access_point" value="alice"/>
253 Afterward simply declare the hosts and routers inside the WiFi network. Remember
254 that one must have the same name as declared in the property "access point".
258 <router id="alice" speed="1Gf"/>
259 <host id="STA0-0" speed="1Gf"/>
260 <host id="STA0-1" speed="1Gf"/>
262 Finally, close the WiFi zone.
268 The WiFi zone may be connected to another zone using a traditional link and
269 a zoneRoute. Note that the connection between two zones is always wired.
273 <link id="wireline" bandwidth="100Mbps" latency="2ms" sharing_policy="SHARED"/>
275 <zoneRoute src="SSID_1" dst="SSID_2" gw_src="alice" gw_dst="bob">
276 <link_ctn id="wireline"/>
279 WiFi network performance
280 """"""""""""""""""""""""
282 The performance of a wifi network is controlled by 3 property that can be added
283 to hosts connected to the wifi zone:
285 * ``mcs`` (`Modulation and Coding Scheme <https://en.wikipedia.org/wiki/Link_adaptation>`_)
286 Roughly speaking, it defines the speed at which the access point is
287 exchanging data with all stations. It depends on its model and configuration,
288 and the possible values are listed for example on Wikipedia.
289 |br| By default, ``mcs=3``.
290 It is a property of the WiFi zone.
291 * ``nss`` (Number of Spatial Streams, or `number of antennas <https://en.wikipedia.org/wiki/IEEE_802.11n-2009#Number_of_antennas>`_)
292 defines the amount of simultaneous data streams that the AP can sustain.
293 Not all value of MCS and NSS are valid nor compatible (cf. `802.11n standard <https://en.wikipedia.org/wiki/IEEE_802.11n-2009#Data_rates>`_).
294 |br| By default, ``nss=1``.
295 It is a property of the WiFi zone.
296 * ``wifi_distance`` is the distance from the station to the access point. Each
297 station can have a specific value.
298 |br| By default, ``wifi_distance=10``.
299 It is a property of stations of the WiFi network.
301 Here is an example of a zone changing ``mcs`` and ``nss`` values.
305 <zone id="SSID_1" routing="WIFI">
306 <prop id="access_point" value="alice"/>
307 <prop id="mcs" value="2"/>
308 <prop id="nss" value="2"/>
312 Here is an example of a host changing ``wifi_distance`` value.
316 <host id="STA0-0" speed="1Gf">
317 <prop id="wifi_distance" value="37"/>
320 Random Number Generator
321 -----------------------
323 It is possible to define a fixed or random seed to the ns3 random number
324 generator using the config tag.
328 <?xml version='1.0'?><!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
329 <platform version="4.1">
331 <prop id = "network/model" value = "ns-3" />
332 <prop id = "ns3/seed" value = "time" />
337 The first property defines that this platform will be used with the ns3 model.
338 The second property defines the seed that will be used. Defined to ``time``
339 it will use a random seed, defined to a number it will use this number as
345 A ns-3 platform is automatically created from the provided SimGrid
346 platform. However, there are some known caveats:
348 * The default values (e.g., TCP parameters) are the ns-3 default values.
349 * ns-3 networks are routed using the shortest path algorithm, using ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``.
350 * End hosts cannot have more than one interface card. So, your SimGrid hosts
351 should be connected to the platform through only one link. Otherwise, your
352 SimGrid host will be considered as a router (FIXME: is it still true?).
354 Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully readable)
355 as possible. If the current state does not fit your needs, you should modify
356 this plugin, and/or create your own plugin from the existing one. If you come up
357 with interesting improvements, please contribute them back.
362 If your simulation hangs in a communication, this is probably because one host
363 is sending data that is not routable in your platform. Make sure that you only
364 use routes of length 1, and that any host is connected to the platform.
365 Arguably, SimGrid could detect this situation and report it, but unfortunately,
366 this is still to be done.