docs/source/examples.rst

Examples
========

.. role:: red

.. note::
   :red:`!!! This page only shows up examples of how to config topology and perform basic
   operations in ndnSIM (an example equivalent to "Hello, world1") !!!  These are **NOT**
   examples of real experimentations (just like "Hello, world!" is not a real program).`

.. note::
   If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can
   directly run the example without putting scenario into ``scratch/`` folder.

.. note::
   A few mobile simulation scenarios are available. The project code may require a custom version of ndnSIM (see project commits for further details).

   - `Project Repository <https://github.com/4th-ndn-hackathon/ndnSIM-Mobile-Simulation-Package>`__
   - `Vehicle to Infrastructure Example <https://github.com/4th-ndn-hackathon/ndnSIM-Mobile-Simulation-Package/blob/master/examples/simple-wifi-mobility.cpp>`__
   - `Vehicle to Vehicle Example <https://github.com/4th-ndn-hackathon/ndnSIM-Mobile-Simulation-Package/blob/master/examples/ndn-v2v-simple.cpp>`__


.. _simple-scenario:

Simple scenario
---------------

.. sidebar:: Topology

    .. aafig::
        :aspect: 60
        :scale: 90

          +----------+                +--------+                +----------+
          |          |     1Mbps      |        |      1Mbps     |          |
          | Consumer |<-------------->| Router |<-------------->| Producer |
          |          |         10ms   |        |         10ms   |          |
          +----------+                +--------+                +----------+

The first example (``ndn-simple.cpp``) shows very basics of ndnSIM.  In the simulated
topology there are 3 nodes, connected with point-to-point links, one
NDN consumer, and one NDN producer:

Consumer is simulated using :ndnsim:`ConsumerCbr` reference application and generates Interests
towards the producer with frequency of 10 Interests per second (see :doc:`applications`).

Producer is simulated using :ndnsim:`Producer` class, which is used to satisfy all incoming
Interests with virtual payload data (1024 bytes).

FIB on every node is populated using default routes (see :doc:`helpers`) and the content store
structure of the original ndnSIM is used.

The following code represents all that is necessary to run such a
simple scenario

.. literalinclude:: ../../examples/ndn-simple.cpp
   :language: c++
   :linenos:
   :lines: 20-28,49-
   :emphasize-lines: 23-24,27-29,42-53

If this code is placed into ``scratch/ndn-simple.cpp`` and NS-3 is compiled in debug mode, you
can run and see progress of the simulation using the following command (in optimized mode
nothing will be printed out)::

     NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-simple

.. note::
   If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can
   directly run the example without putting scenario into ``scratch/`` folder.

.. _9-node-grid-example:

9-node grid example
-------------------

.. sidebar:: Topology

    .. aafig::
        :aspect: 60
        :scale: 120

        /--------\      /-\         /-\
        |Consumer|<---->| |<------->| |
        \--------/      \-/         \-/
            ^            ^           ^
            |            |           |   1Mbps/10ms delay
            v            v           v
           /-\          /-\         /-\
           | |<-------->| |<------->| |
           \-/          \-/         \-/
            ^            ^           ^
            |            |           |
            v            v           v
           /-\          /-\      /--------\
           | |<-------->| |<---->|Producer|
           \-/          \-/      \--------/

This scenario (``ndn-grid.cpp``) simulates a grid topology, which is constructed using
PointToPointLayout NS-3 module.

FIB is populated using :ndnsim:`GlobalRoutingHelper` (see :doc:`helpers`). The content store
structure of NFD is used in all the nodes.

Consumer is simulated using :ndnsim:`ConsumerCbr` reference application and generates Interests
towards the producer with frequency of 100 interests per second (see :doc:`applications`).

Producer is simulated using :ndnsim:`Producer` class, which is used to satisfy all incoming
Interests with virtual payload data (1024 bytes).

The following code represents all that is necessary to run such a simple scenario

.. literalinclude:: ../../examples/ndn-grid.cpp
   :language: c++
   :linenos:
   :lines: 20-29,54-
   :emphasize-lines: 24-26,33,36-37,40-42,58,61

If this code is placed into ``scratch/ndn-grid.cpp`` and NS-3 is compiled in debug mode, you
can run and see progress of the simulation using the following command (in optimized mode
nothing will be printed out)::

    NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-grid

.. note::
   If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can
   directly run the example without putting scenario into ``scratch/`` folder.

.. _9-node-grid-example-using-topology-plugin:

9-node grid example using topology plugin
-----------------------------------------

.. sidebar:: Topology

    .. aafig::
        :aspect: 60
        :scale: 120

        /--------\      /-\         /-\
        |Consumer|<---->| |<------->| |
        \--------/      \-/         \-/
            ^            ^           ^
            |            |           |   1Mbps/10ms delay
            v            v           v
           /-\          /-\         /-\
           | |<-------->| |<------->| |
           \-/          \-/         \-/
            ^            ^           ^
            |            |           |
            v            v           v
           /-\          /-\      /--------\
           | |<-------->| |<---->|Producer|
           \-/          \-/      \--------/

Instead of defining topology directly as in :ref:`simple-scenario` or using specialized helpers
as in :ref:`9-node-grid-example`, ndnSIM provides experimental extended versions of
TopologyReader classes: :ndnsim:`AnnotatedTopologyReader` and
:ndnsim:`RocketfuelWeightsReader`.

While :ndnsim:`RocketfuelWeightsReader` is a specialized version intended to be used with
`Rocketfuel <https://www.cs.washington.edu/research/networking/rocketfuel/>`_ topology and link
weights files (examples will be provided later), :ndnsim:`AnnotatedTopologyReader` is a more
general-use class that uses simple user-readable format.

:ndnsim:`AnnotatedTopologyReader` expects the following format:

.. literalinclude:: ../../examples/topologies/topo-grid-3x3.txt
   :language: bash
   :linenos:
   :lines: 1-2,19-
   :emphasize-lines: 8,24


This scenario (``ndn-grid-topo-plugin.cpp``) duplicates the functionality of
:ref:`9-node-grid-example` but with the use of :ndnsim:`AnnotatedTopologyReader`.

.. literalinclude:: ../../examples/ndn-grid-topo-plugin.cpp
   :language: c++
   :linenos:
   :lines: 20-27,52-
   :emphasize-lines: 15-17,31-33

As you can see, scenario code became more compact and more readable.

:ndnsim:`AnnotatedTopologyReader` provides two ways to access topology nodes.  First, you can
use the method :ndnsim:`AnnotatedTopologyReader::GetNodes` which returns NodeContainer.

Alternatively, nodes can be accessed by name using `Names::Find<Node> ("nodename")` call, as in
the above example.  For this purpose,:ndnsim:`AnnotatedTopologyReader` automatically registers
all created nodes with names specified in topology file.  For more information about `Names`
class, please refer to `NS-3 documentation <https://www.nsnam.org/doxygen/classns3_1_1_names.html>`_.

If the topology file is placed into ``src/ndnSIM/examples/topologies/topo-grid-3x3.txt`` and
the code is placed into ``scratch/ndn-grid-topo-plugin.cpp``, you can run and see progress of
the simulation using the following command (in optimized mode nothing will be printed out)::

    NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-grid-topo-plugin

.. note::
   If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can
   directly run the example without putting scenario into ``scratch/`` folder.

6-node bottleneck topology
--------------------------

.. sidebar:: Topology

    .. aafig::
        :aspect: 60
        :scale: 90

         /------\                                                    /------\
         | Src1 |<--+                                            +-->| Dst1 |
         \------/    \                                          /    \------/
                      \                                        /
                       +-->/------\   "bottleneck"  /------\<-+
                           | Rtr1 |<===============>| Rtr2 |
                       +-->\------/                 \------/<-+
                      /                                        \
         /------\    /                                          \    /------\
         | Src2 |<--+                                            +-->| Dst2 |
         \------/                                                    \------/


This scenario (``ndn-congestion-topo-plugin.cpp``) can be used for congestion-related scenarios

.. literalinclude:: ../../examples/topologies/topo-6-node.txt
    :language: bash
    :linenos:
    :lines: 1-2,15-

.. literalinclude:: ../../examples/ndn-congestion-topo-plugin.cpp
   :language: c++
   :linenos:
   :lines: 20-27,48-

To run this scenario and see what is happening, use the following command::

        NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-congestion-topo-plugin

.. note::
   If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can
   directly run the example without putting scenario into ``scratch/`` folder.

.. _11-node 2-bottleneck topology:

11-node 2-bottleneck topology
------------------------------

.. sidebar:: Topology

    .. aafig::
        :aspect: 60
        :scale: 90

         /------\ 0                                                 0 /------\
         |  c1  |<-----+                                       +----->|  p1  |
         \------/       \                                     /       \------/
                         \              /-----\              /
         /------\ 0       \         +==>| r12 |<==+         /       0 /------\
         |  c2  |<--+      \       /    \-----/    \       /      +-->|  p2  |
         \------/    \      \     |                 |     /      /    \------/
                      \      |    |   1Mbps links   |    |      /
                       \  1  v0   v5               1v   2v  3  /
                        +->/------\                 /------\<-+
                          2|  r1  |<===============>|  r2  |4
                        +->\------/4               0\------/<-+
                       /    3^                           ^5    \
                      /      |                           |      \
         /------\ 0  /      /                             \      \  0 /------\
         |  c3  |<--+      /                               \      +-->|  p3  |
         \------/         /                                 \         \------/
                         /     "All consumer-router and"     \
         /------\ 0     /      "router-producer links are"    \    0 /------\
         |  c4  |<-----+       "10Mbps"                        +---->|  p4  |
         \------/                                                    \------/

         "Numbers near nodes denote face IDs. Face ID is assigned based on the order of link"
         "definitions in the topology file"

Firstly, we define a meaningful topology:

The corresponding topology file (``topo-11-node-two-bottlenecks.txt``):

.. literalinclude:: ../../examples/topologies/topo-11-node-two-bottlenecks.txt
    :language: bash
    :linenos:
    :lines: 1-2,28-

After that, we define the simulation scenario:

Example simulation (``ndn-congestion-alt-topo-plugin.cpp``) scenario:

.. literalinclude:: ../../examples/ndn-congestion-alt-topo-plugin.cpp
    :language: c++
    :linenos:
    :lines: 20-27,60-

To run this scenario and see what is happening, use the following command::

        NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-congestion-alt-topo-plugin

You can also run using visualizer module to verify that both bottleneck links are utilized::

        ./waf --run=ndn-congestion-alt-topo-plugin --visualize

.. note::
   If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can
   directly run the example without putting scenario into ``scratch/`` folder.

.. _6-node topology with custom NFD forwarding strategy:

6-node topology with custom NFD forwarding strategy
---------------------------------------------------

.. sidebar:: Topology

    .. aafig::
        :aspect: 60
        :scale: 90

                                /-----\
                                | CSU |
                       +----->  | HUB |  <----+
                       |        \-----/       |
                       |                      |  1Mbps/10ms delay
                       v                      v
                     /------\               /----------\
                     | UCLA |               | Consumer |
                     | HUB  |               |   CSU-1  |
             +-----> \------/ <-----+       \----------/
             |                      |
             |                      |
             v                      v
         /----------\           /----------\
         | Producer |           | Producer |
         |  UCLA-1  |           |  UCLA-2  |
         \----------/           \----------/

        "All links are 1Mbps with propagation 10ms delay."
        "FIB is populated using NdnGlobalRoutingHelper."

This scenario simulates a load balancer topology (using topology reader module).  The
corresponding topology file (``topo-load-balancer.txt``):

.. literalinclude:: ../../examples/topologies/topo-load-balancer.txt
    :language: bash
    :linenos:
    :lines: 30-36,43-

After that, we define the simulation scenario:

Example simulation (``ndn-load-balancer.cpp``) scenario:

.. literalinclude:: ../../examples/ndn-load-balancer.cpp
    :language: c++
    :linenos:
    :lines: 20-27,55-
    :emphasize-lines: 7,44-45

In this simulation scenario, the node called "UCLA-HUB" implements a random load balancing
strategy for the name prefix "/ucla/hello". In this way, the Interest packets will be
forwarded randomly either to the producer node called "UCLA-1" or the producer node called
"UCLA-2".

To run this scenario and see what is happening, use the following command::

        NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-load-balancer

.. note::
   If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can
   directly run the example without putting scenario into ``scratch/`` folder.

9-node grid topology with different forwarding strategies per name prefix
-------------------------------------------------------------------------

This scenario simulates a grid topology (using PointToPointGrid module). In this scenario,
thanks to NFD, we can choose a different forwarding strategy for each prefix in each node.

Consumer requests data from producer with frequency 100 interests per second (interests
contain constantly increasing sequence number).

For every received interest, producer replies with a data packet, containing 1024 bytes of
virtual payload.

In this scenario, we choose the multicast strategy to be installed for the name prefix
"/prefix1" in all the nodes, while for the name prefix "/prefix2", the best-route strategy
will be installed in all the topology nodes.

Example simulation (``ndn-different-strategy-per-prefix.cpp``) scenario:

.. literalinclude:: ../../examples/ndn-different-strategy-per-prefix.cpp
    :language: c++
    :linenos:
    :lines: 20-33,61-
    :emphasize-lines: 51-52

To run this scenario and see what is happening, use the following command::

        NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-different-strategy-per-prefix

9-node grid topology with different forwarding strategy for each node
---------------------------------------------------------------------

This scenario simulates a grid topology (using PointToPointGrid module). The first six nodes
use the best route forwarding strategy, whereas the three remaining nodes use the multicast
forwarding strategy.

Consumer requests data from producer with frequency 100 interests per second (interests
contain constantly increasing sequence number).

For every received interest, producer replies with a data packet, containing 1024 bytes of
virtual payload.

Example simulation (``ndn-grid-multiple-strategies.cpp``) scenario:

.. literalinclude:: ../../examples/ndn-grid-multiple-strategies.cpp
    :language: c++
    :linenos:
    :lines: 20-33,61-
    :emphasize-lines: 49-58

To run this scenario and see what is happening, use the following command::

        NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-grid-multiple-strategies

Simple parallel scenario using MPI
----------------------------------

:ref:`simple scenario with MPI support`

3-level binary tree with packet-level trace helpers
---------------------------------------------------

:ref:`packet trace helper example`


3-level binary tree with content store trace helper
---------------------------------------------------

:ref:`cs trace helper example`

3-level binary tree with  application-level Interest-Data delay tracer
----------------------------------------------------------------------

:ref:`app delay trace helper example`

1-node topology with custom application
---------------------------------------

:ref:`Custom applications`

Simple scenario with pcap dump
------------------------------

The following example (``ndn-simple-with-pcap.cpp``) demonstrates how to dump all simulated
traffic in pcap-formatted data, which can be used for later analysis by conventional tools,
like tcpdump and wireshark.

.. literalinclude:: ../../examples/ndn-simple-with-pcap.cpp
   :language: c++
   :linenos:
   :lines: 20-
   :emphasize-lines: 24-43,89-91

If this code is placed into ``scratch/ndn-simple-with-pcap.cpp`` and NS-3 is compiled in debug
mode, you can run and see progress of the simulation using the following command (in optimized
mode nothing will be printed out)::

     NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-simple-with-pcap

This will generate ``ndn-simple-trace.pcap``, which can be fed to tcpdump::

     tcpdump -r ndn-simple-trace.pcap

.. note::
   If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can
   directly run the example without putting scenario into ``scratch/`` folder.

.. _Simple scenario with link failures:

Simple scenario with link failures
----------------------------------

The following example (``ndn-simple-with-link-failure.cpp``) shows how to "fail" links in
ndnSIM simulation.  The basic idea is to set ndn::Faces that correspond to the failed link to
DOWN state.  ndnSIM now includes a simple helper that simplifies this process.

.. literalinclude:: ../../examples/ndn-simple-with-link-failure.cpp
   :language: c++
   :linenos:
   :lines: 20-31,52-
   :emphasize-lines: 56-57

If this code is placed into ``scratch/ndn-simple-with-link-failure.cpp`` and NS-3 is compiled
in debug mode, you can run and see progress of the simulation using the following command (in
optimized mode nothing will be printed out)::

     NS_LOG=ndn.Consumer:ndn.Producer:ndn.LinkControlHelper ./waf --run=ndn-simple-with-link-failure

.. note::
   If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can
   directly run the example without putting scenario into ``scratch/`` folder.


25-node tree topology with L2Tracer
-----------------------------------

:ref:`Example of packet drop tracer (L2Tracer)`


LFID (Loop-Free Inport-Dependent) Routing for ndnSIM
----------------------------------------------------

LFID (Loop-Free Inport-Dependent) Routing extends the ndnSIM route calculation to provide loop-free and on average shorter loop-free paths than existing work.
For details see the `tech report. <https://named-data.net/publications/techreports/mp_routing_tech_report/>`__

LFID provides a better trade-off than the existing route calculation algorithms:

1. ``CalculateRoutes():`` Only provides a single shortest path nexthop.
2. ``CalculateAllPossibleRoutes():`` Provides all possible nexthops, but many of them lead to loops.

LFID, on the other hand, maximizes the nexthop choice while also completely avoiding loops.


We provide two example topologies (abilene and grid) to compare against the existing route calculation methods:

.. literalinclude:: ../../examples/lfid.cpp
   :language: c++
   :linenos:
   :lines: 71-148


Simply run::

     ./waf --run "lfid [--grid] [--routing={lfid|sp|allroutes}]"

The output will show the nexthops at each node for the given name prefix, and any loops during forwarding.