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
36 accounts for three phenomena that directly impact the simulation time even
37 on such a simple example:
39 - The size of a message at the application level (i.e., 100kB in this
40 example) is not the size that will actually be transferred over the
41 network. To mimic the fact that TCP and IP headers are added to each packet of
42 the original payload, the TCP model of SimGrid empirically considers that
43 `only 97% of the nominal bandwidth` are available. In other words, the
44 size of your message is increased by a few percents, whatever this size be.
46 - In the real world, the TCP protocol is not able to fully exploit the
47 bandwidth of a link from the emission of the first packet. To reflect this
48 `slow start` phenomenon, the latency declared in the platform file is
49 multiplied by `a factor of 13.01`. Here again, this is an empirically
50 determined value that may not correspond to every TCP implementations on
51 every networks. It can be tuned when more realistic simulated times for
52 short messages are needed though.
54 - When data is transferred from A to B, some TCP ACK messages travel in the
55 opposite direction. To reflect the impact of this `cross-traffic`, SimGrid
56 simulates a flow from B to A that represents an additional bandwidth
57 consumption of `0.05`. The route from B to A is implicitly declared in the
58 platform file and uses the same link `link1` as if the two hosts were
59 connected through a communication bus. The bandwidth share allocated to the
60 flow from A to B is then the available bandwidth of `link1` (i.e., 97% of
61 the nominal bandwidth of 1Mb/s) divided by 1.05 (i.e., the total consumption).
62 This feature, activated by default, can be disabled by adding the
63 `--cfg=network/crosstraffic:0` flag to command line.
65 As a consequence, the time to transfer 100kB from A to B as simulated by the
66 default TCP model of SimGrid is not 0.81 seconds but
68 .. code-block:: python
70 0.01 * 13.01 + 800000 / ((0.97 * 1e6) / 1.05) = 0.996079 seconds.
74 ns-3 as a SimGrid model
75 ***********************
77 You can use the well-known `ns-3 packet-level network simulator
78 <http://www.nsnam.org>`_ as a SimGrid model, for example to investigate the
79 validity of your simulation. Just install ns-3 and recompile SimGrid
82 The SimGrid/ns-3 binding only contains features that are common to both systems.
83 Not all ns-3 models are available from SimGrid (only the TCP and WiFi ones are),
84 while not all SimGrid platform files can be used in conjunction ns-3 (routes
85 must be of length 1). Also, the platform built in ns-3 from the SimGrid
86 description is very basic. Finally, communicating from a host to
87 itself is forbidden in ns-3, so every such communication completes
88 immediately upon startup.
91 Compiling the ns-3/SimGrid binding
92 ==================================
97 SimGrid requires ns-3 version 3.26 or higher, and you probably want the most
98 recent version of both SimGrid and ns-3. While the Debian package of SimGrid
99 don't have the ns-3 bindings activated, you can still use the packaged version
100 of ns-3 by grabbing the ``libns3-dev ns3`` packages. Alternatively, you can
101 install ns-3 from scratch (see the `ns-3 documentation <http://www.nsnam.org>`_).
103 Enabling ns-3 in SimGrid
104 ------------------------
106 SimGrid must be recompiled with the ``enable_ns3`` option activated in cmake.
107 Optionally, use ``NS3_HINT`` to tell cmake where ns3 is installed on
110 .. code-block:: shell
112 cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed
114 By the end of the configuration, cmake reports whether ns-3 was found,
115 and this information is also available in ``include/simgrid/config.h``
116 If your local copy defines the variable ``SIMGRID_HAVE_NS3`` to 1, then ns-3
117 was correctly detected. Otherwise, explore ``CMakeFiles/CMakeOutput.log`` and
118 ``CMakeFiles/CMakeError.log`` to diagnose the problem.
120 Test that ns-3 was successfully integrated with the following (from your SimGrid
121 build directory). It will run all SimGrid tests that are related to the ns-3
122 integration. If no test is run at all, you probably forgot to enable ns-3 in cmake.
124 .. code-block:: shell
131 If you use a version of ns-3 that is not known to SimGrid yet, edit
132 ``tools/cmake/Modules/FindNS3.cmake`` in your SimGrid tree, according to the
133 comments on top of this file. Conversely, if something goes wrong with an old
134 version of either SimGrid or ns-3, try upgrading everything.
138 Using ns-3 from SimGrid
139 =======================
141 Platform files compatibility
142 ----------------------------
144 Any route longer than one will be ignored when using ns-3. They are
145 harmless, but you still need to connect your hosts using one-hop routes.
146 The best solution is to add routers to split your route. Here is an
147 example of an invalid platform:
151 <?xml version='1.0'?>
152 <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
153 <platform version="4.1">
154 <zone id="zone0" routing="Floyd">
155 <host id="alice" speed="1Gf" />
156 <host id="bob" speed="1Gf" />
158 <link id="l1" bandwidth="1Mbps" latency="5ms" />
159 <link id="l2" bandwidth="1Mbps" latency="5ms" />
161 <route src="alice" dst="bob">
162 <link_ctn id="l1"/> <!-- !!!! IGNORED WHEN USED WITH ns-3 !!!! -->
163 <link_ctn id="l2"/> <!-- !!!! ROUTES MUST CONTAIN ONE LINK ONLY !!!! -->
168 This can be reformulated as follows to make it usable with the ns-3 binding.
169 There is no direct connection from alice to bob, but that's OK because ns-3
170 automatically routes from point to point (using
171 ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``).
175 <?xml version='1.0'?>
176 <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
177 <platform version="4.1">
178 <zone id="zone0" routing="Full">
179 <host id="alice" speed="1Gf" />
180 <host id="bob" speed="1Gf" />
182 <router id="r1" /> <!-- routers are compute-less hosts -->
184 <link id="l1" bandwidth="1Mbps" latency="5ms"/>
185 <link id="l2" bandwidth="1Mbps" latency="5ms"/>
187 <route src="alice" dst="r1">
191 <route src="r1" dst="bob">
197 Once your platform is OK, just change the :ref:`network/model
198 <options_model_select>` configuration option to `ns-3` as follows. The other
199 options can be used as usual.
201 .. code-block:: shell
203 ./network-ns3 --cfg=network/model:ns-3 (other parameters)
205 Many other files from the ``examples/platform`` directory are usable with the
206 ns-3 model, such as `examples/platforms/dogbone.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/dogbone.xml>`_.
207 Check the file `examples/cpp/network-ns3/network-ns3.tesh <https://framagit.org/simgrid/simgrid/tree/master/examples/cpp/network-ns3/network-ns3.tesh>`_
208 to see which ones are used in our regression tests.
213 In SimGrid, WiFi networks are modeled with WiFi zones, where a zone contains
214 the access point of the WiFi network and the hosts connected to it (called
215 station in the WiFi world). Links inside WiFi zones are modeled as regular
216 links with a specific attribute, and these links are then added to routes
217 between hosts. The main difference When using ns-3 WiFi networks is that
218 the network performance is not given by the link bandwidth and latency but
219 by the access point WiFi characteristics, and the distance between the access
222 So, to declare a new WiFi network, simply declare a zone with the ``WIFI``
227 <zone id="SSID_1" routing="WIFI">
229 Inside this zone you must declare which host or router will be the access point
234 <prop id="access_point" value="alice"/>
236 Afterward simply declare the hosts and routers inside the WiFi network. Remember
237 that one must have the same name as declared in the property "access point".
241 <router id="alice" speed="1Gf"/>
242 <host id="STA0-0" speed="1Gf"/>
243 <host id="STA0-1" speed="1Gf"/>
245 Finally, close the WiFi zone.
251 The WiFi zone may be connected to another zone using a traditional link and
252 a zoneRoute. Note that the connection between two zones is always wired.
256 <link id="wireline" bandwidth="100Mbps" latency="2ms" sharing_policy="SHARED"/>
258 <zoneRoute src="SSID_1" dst="SSID_2" gw_src="alice" gw_dst="bob">
259 <link_ctn id="wireline"/>
262 WiFi network performance
263 """"""""""""""""""""""""
265 The performance of a wifi network is controlled by 3 property that can be added
266 to hosts connected to the wifi zone:
268 * ``mcs`` (`Modulation and Coding Scheme <https://en.wikipedia.org/wiki/Link_adaptation>`_)
269 Roughly speaking, it defines the speed at which the access point is
270 exchanging data with all stations. It depends on its model and configuration,
271 and the possible values are listed for example on Wikipedia.
272 |br| By default, ``mcs=3``.
273 It is a property of the WiFi zone.
274 * ``nss`` (Number of Spatial Streams, or `number of antennas <https://en.wikipedia.org/wiki/IEEE_802.11n-2009#Number_of_antennas>`_)
275 defines the amount of simultaneous data streams that the AP can sustain.
276 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>`_).
277 |br| By default, ``nss=1``.
278 It is a property of the WiFi zone.
279 * ``wifi_distance`` is the distance from the station to the access point. Each
280 station can have a specific value.
281 |br| By default, ``wifi_distance=10``.
282 It is a property of stations of the WiFi network.
284 Here is an example of a zone changing ``mcs`` and ``nss`` values.
288 <zone id="SSID_1" routing="WIFI">
289 <prop id="access_point" value="alice"/>
290 <prop id="mcs" value="2"/>
291 <prop id="nss" value="2"/>
295 Here is an example of a host changing ``wifi_distance`` value.
299 <host id="STA0-0" speed="1Gf">
300 <prop id="wifi_distance" value="37"/>
303 Random Number Generator
304 -----------------------
306 It is possible to define a fixed or random seed to the ns3 random number
307 generator using the config tag.
311 <?xml version='1.0'?><!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
312 <platform version="4.1">
314 <prop id = "network/model" value = "ns-3" />
315 <prop id = "ns3/seed" value = "time" />
320 The first property defines that this platform will be used with the ns3 model.
321 The second property defines the seed that will be used. Defined to ``time``
322 it will use a random seed, defined to a number it will use this number as
328 A ns-3 platform is automatically created from the provided SimGrid
329 platform. However, there are some known caveats:
331 * The default values (e.g., TCP parameters) are the ns-3 default values.
332 * ns-3 networks are routed using the shortest path algorithm, using ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``.
333 * End hosts cannot have more than one interface card. So, your SimGrid hosts
334 should be connected to the platform through only one link. Otherwise, your
335 SimGrid host will be considered as a router (FIXME: is it still true?).
337 Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully readable)
338 as possible. If the current state does not fit your needs, you should modify
339 this plugin, and/or create your own plugin from the existing one. If you come up
340 with interesting improvements, please contribute them back.
345 If your simulation hangs in a communication, this is probably because one host
346 is sending data that is not routable in your platform. Make sure that you only
347 use routes of length 1, and that any host is connected to the platform.
348 Arguably, SimGrid could detect this situation and report it, but unfortunately,
349 this is still to be done.