that this communication would take `0.81` seconds to complete according to a
simple latency-plus-size-divided-by-bandwidth model (0.01 + 8e5/1e6 = 0.81).
However, the default TCP model of SimGrid is a bit more complex than that. It
-
accounts for three phenomena that directly impact the simulation time even
on such a simple example:
Optionally, use ``NS3_HINT`` to tell cmake where ns3 is installed on
your disk.
-.. code-block:: shell
+.. code-block:: console
- cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed
+ $ cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed
By the end of the configuration, cmake reports whether ns-3 was found,
and this information is also available in ``include/simgrid/config.h``
build directory). It will run all SimGrid tests that are related to the ns-3
integration. If no test is run at all, you probably forgot to enable ns-3 in cmake.
-.. code-block:: shell
+.. code-block:: console
- ctest -R ns3
+ $ ctest -R ns3
Troubleshooting
---------------
comments on top of this file. Conversely, if something goes wrong with an old
version of either SimGrid or ns-3, try upgrading everything.
+Note that there is a known bug with version 3.31 of ns3, when it's built with
+MPI support, like it is with the package libns3-dev in Debian 11 « Bullseye ».
+A simple workaround is to edit the file
+``/usr/include/ns3.31/ns3/point-to-point-helper.h`` to remove the ``#ifdef NS3_MPI``
+include guard. This can be achieved with the following command (as root):
+
+.. code-block:: console
+
+ # sed -i '/^#ifdef NS3_MPI/,+2s,^#,//&,' /usr/include/ns3.31/ns3/point-to-point-helper.h
+
.. _ns3_use:
Using ns-3 from SimGrid
<zone id="zone0" routing="Floyd">
<host id="alice" speed="1Gf" />
<host id="bob" speed="1Gf" />
-
+
<link id="l1" bandwidth="1Mbps" latency="5ms" />
<link id="l2" bandwidth="1Mbps" latency="5ms" />
</route>
</zone>
</platform>
-
+
This can be reformulated as follows to make it usable with the ns-3 binding.
There is no direct connection from alice to bob, but that's OK because ns-3
automatically routes from point to point (using
<link id="l2" bandwidth="1Mbps" latency="5ms"/>
<route src="alice" dst="r1">
- <link_ctn id="l1"/>
+ <link_ctn id="l1"/>
</route>
-
+
<route src="r1" dst="bob">
- <link_ctn id="l2"/>
+ <link_ctn id="l2"/>
</route>
</zone>
</platform>
<options_model_select>` configuration option to `ns-3` as follows. The other
options can be used as usual.
-.. code-block:: shell
+.. code-block:: console
- ./network-ns3 --cfg=network/model:ns-3 (other parameters)
+ $ ./network-ns3 --cfg=network/model:ns-3 (other parameters)
Many other files from the ``examples/platform`` directory are usable with the
ns-3 model, such as `examples/platforms/dogbone.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/dogbone.xml>`_.
Check the file `examples/cpp/network-ns3/network-ns3.tesh <https://framagit.org/simgrid/simgrid/tree/master/examples/cpp/network-ns3/network-ns3.tesh>`_
to see which ones are used in our regression tests.
+Alternatively, you can manually modify the ns-3 settings by retrieving
+the ns-3 node from any given host with the
+:cpp:func:`simgrid::get_ns3node_from_sghost` function (defined in
+``simgrid/plugins/ns3.hpp``).
+
+.. doxygenfunction:: simgrid::get_ns3node_from_sghost
+
+
WiFi platforms
^^^^^^^^^^^^^^
-In SimGrid, WiFi networks are modeled with WiFi zones, where a zone contains
-the access point of the WiFi network and the hosts connected to it (called
-station in the WiFi world). Links inside WiFi zones are modeled as regular
-links with a specific attribute, and these links are then added to routes
-between hosts. The main difference When using ns-3 WiFi networks is that
-the network performance is not given by the link bandwidth and latency but
-by the access point WiFi characteristics, and the distance between the access
+In SimGrid, WiFi networks are modeled with WiFi zones, where a zone contains
+the access point of the WiFi network and the hosts connected to it (called
+station in the WiFi world). Links inside WiFi zones are modeled as regular
+links with a specific attribute, and these links are then added to routes
+between hosts. The main difference When using ns-3 WiFi networks is that
+the network performance is not given by the link bandwidth and latency but
+by the access point WiFi characteristics, and the distance between the access
point and the hosts.
So, to declare a new WiFi network, simply declare a zone with the ``WIFI``
<prop id="access_point" value="alice"/>
-Afterward simply declare the hosts and routers inside the WiFi network. Remember
+Afterward simply declare the hosts and routers inside the WiFi network. Remember
that one must have the same name as declared in the property "access point".
.. code-block:: xml
<router id="alice" speed="1Gf"/>
<host id="STA0-0" speed="1Gf"/>
- <host id="STA0-1" speed="1Gf"/>
+ <host id="STA0-1" speed="1Gf"/>
Finally, close the WiFi zone.
</zone>
-The WiFi zone may be connected to another zone using a traditional link and
+The WiFi zone may be connected to another zone using a traditional link and
a zoneRoute. Note that the connection between two zones is always wired.
.. code-block:: xml
Roughly speaking, it defines the speed at which the access point is
exchanging data with all stations. It depends on its model and configuration,
and the possible values are listed for example on Wikipedia.
- |br| By default, ``mcs=3``.
+ |br| By default, ``mcs=3``.
It is a property of the WiFi zone.
* ``nss`` (Number of Spatial Streams, or `number of antennas <https://en.wikipedia.org/wiki/IEEE_802.11n-2009#Number_of_antennas>`_)
defines the amount of simultaneous data streams that the AP can sustain.
Random Number Generator
-----------------------
-It is possible to define a fixed or random seed to the ns3 random number
+It is possible to define a fixed or random seed to the ns3 random number
generator using the config tag.
.. code-block:: xml
<platform version="4.1">
<config>
<prop id = "network/model" value = "ns-3" />
- <prop id = "ns3/seed" value = "time" />
+ <prop id = "ns3/seed" value = "time" />
</config>
- ...
+ ...
</platform>
The first property defines that this platform will be used with the ns3 model.
-The second property defines the seed that will be used. Defined to ``time``
-it will use a random seed, defined to a number it will use this number as
+The second property defines the seed that will be used. Defined to ``time``
+it will use a random seed, defined to a number it will use this number as
the seed.
Limitations
* End hosts cannot have more than one interface card. So, your SimGrid hosts
should be connected to the platform through only one link. Otherwise, your
SimGrid host will be considered as a router (FIXME: is it still true?).
-
+
Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully readable)
as possible. If the current state does not fit your needs, you should modify
this plugin, and/or create your own plugin from the existing one. If you come up
