blob: d99c245eaae4d1d4ee5fcfe057522847f1d9e03d [file] [log] [blame]
Alexander Afanasyev4d325162012-06-01 12:28:50 -07001Examples
2========
3
Alexander Afanasyev6dbacda2012-10-23 17:20:18 -07004.. _simple-scenario:
5
Alexander Afanasyev4d325162012-06-01 12:28:50 -07006Simple scenario
7---------------
8
Alexander Afanasyevb8d14ad2012-08-09 13:19:37 -07009The first example (``ndn-simple.cc``) shows very basics of ndnSIM. In the simulated
Alexander Afanasyev4d325162012-06-01 12:28:50 -070010topology there are 3 nodes, connected with point-to-point links, one
Alexander Afanasyev07b00632012-06-01 23:46:47 -070011NDN consumer, and one NDN producer:
Alexander Afanasyev4d325162012-06-01 12:28:50 -070012
Alexander Afanasyev07b00632012-06-01 23:46:47 -070013.. aafig::
14 :aspect: 60
15 :scale: 120
Alexander Afanasyev4d325162012-06-01 12:28:50 -070016
Alexander Afanasyev07b00632012-06-01 23:46:47 -070017 +----------+ +--------+ +----------+
18 | | 1Mbps | | 1Mbps | |
19 | Consumer |<-------------->| Router |<-------------->| Producer |
20 | | 10ms | | 10ms | |
21 +----------+ +--------+ +----------+
Alexander Afanasyev4d325162012-06-01 12:28:50 -070022
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070023Consumer is simulated using :ndnsim:`ConsumerCbr` reference application and generates Interests towards the producer
Alexander Afanasyev07b00632012-06-01 23:46:47 -070024with frequency of 10 Interests per second (see :doc:`applications`).
25
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070026Producer is simulated using :ndnsim:`Producer` class, which is used to satisfy all incoming Interests with virtual payload data (1024 bytes).
Alexander Afanasyev07b00632012-06-01 23:46:47 -070027
28FIB on every node is populated using default routes (see :doc:`helpers`).
Alexander Afanasyev4d325162012-06-01 12:28:50 -070029
30The following code represents all that is necessary to run such a
31simple scenario
32
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -080033.. literalinclude:: ../../examples/ndn-simple.cc
34 :language: c++
35 :linenos:
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080036 :lines: 20-27,48-
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -080037 :emphasize-lines: 30-33,37-49
Alexander Afanasyev07b00632012-06-01 23:46:47 -070038
Alexander Afanasyevb8d14ad2012-08-09 13:19:37 -070039If this code is placed into ``scratch/ndn-simple.cc`` and NS-3 is compiled in debug mode, you can run and see progress of the
Alexander Afanasyev07b00632012-06-01 23:46:47 -070040simulation using the following command (in optimized mode nothing will be printed out)::
41
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070042 NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-simple
Alexander Afanasyev07b00632012-06-01 23:46:47 -070043
44
Alexander Afanasyev6dbacda2012-10-23 17:20:18 -070045.. _9-node-grid-example:
46
Alexander Afanasyev07b00632012-06-01 23:46:47 -0700479-node grid example
48-------------------
49
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -080050This scenario (``ndn-grid.cc``) simulates a grid topology, which is constructed using PointToPointLayout NS-3 module
Alexander Afanasyev07b00632012-06-01 23:46:47 -070051
52.. aafig::
53 :aspect: 60
54 :scale: 120
55
56 /--------\ /-\ /-\
57 |Consumer|<---->| |<------->| |
58 \--------/ \-/ \-/
59 ^ ^ ^
60 | | | 1Mbps/10ms delay
61 v v v
62 /-\ /-\ /-\
63 | |<-------->| |<------->| |
64 \-/ \-/ \-/
65 ^ ^ ^
66 | | |
67 v v v
68 /-\ /-\ /--------\
69 | |<-------->| |<---->|Producer|
70 \-/ \-/ \--------/
71
72
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070073FIB is populated using :ndnsim:`GlobalRoutingHelper` (see :doc:`helpers`).
Alexander Afanasyev07b00632012-06-01 23:46:47 -070074
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070075Consumer is simulated using :ndnsim:`ConsumerCbr` reference application and generates Interests towards the producer
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080076with frequency of 100 interests per second (see :doc:`applications`).
Alexander Afanasyev07b00632012-06-01 23:46:47 -070077
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070078Producer is simulated using :ndnsim:`Producer` class, which is used to satisfy all incoming Interests with virtual payload data (1024 bytes).
Alexander Afanasyev07b00632012-06-01 23:46:47 -070079
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -080080The following code represents all that is necessary to run such a simple scenario
Alexander Afanasyev07b00632012-06-01 23:46:47 -070081
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -080082.. literalinclude:: ../../examples/ndn-grid.cc
83 :language: c++
84 :linenos:
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080085 :lines: 20-27,53-
86 :emphasize-lines: 28,31-33,35-38,53-57
Alexander Afanasyev4d325162012-06-01 12:28:50 -070087
Alexander Afanasyev4d325162012-06-01 12:28:50 -070088
Alexander Afanasyevb8d14ad2012-08-09 13:19:37 -070089If this code is placed into ``scratch/ndn-grid.cc`` and NS-3 is compiled in debug mode, you can run and see progress of the
Alexander Afanasyev07b00632012-06-01 23:46:47 -070090simulation using the following command (in optimized mode nothing will be printed out)::
91
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070092 NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-grid
Alexander Afanasyev07b00632012-06-01 23:46:47 -070093
Alexander Afanasyev6dbacda2012-10-23 17:20:18 -070094.. _9-node-grid-example-using-topology-plugin:
95
969-node grid example using topology plugin
97-----------------------------------------
98
99Instead 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`.
100
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800101While :ndnsim:`RocketfuelWeightsReader` is a specialized version intended to be used with `Rocketfuel <http://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.
102
103:ndnsim:`AnnotatedTopologyReader` expects the following format:
Alexander Afanasyev6dbacda2012-10-23 17:20:18 -0700104
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -0800105.. literalinclude:: ../../examples/topologies/topo-grid-3x3.txt
106 :language: bash
107 :linenos:
Alexander Afanasyeve97c6072012-11-21 23:51:12 -0800108 :lines: 1-2,19-
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -0800109 :emphasize-lines: 8,24
Alexander Afanasyev6dbacda2012-10-23 17:20:18 -0700110
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800111
112This scenario (``ndn-grid-topo-plugin.cc``) duplicates the functionality of :ref:`9-node-grid-example` but with the use of :ndnsim:`AnnotatedTopologyReader`.
113
114.. aafig::
115 :aspect: 60
116 :scale: 120
117
118 /--------\ /-\ /-\
119 |Consumer|<---->| |<------->| |
120 \--------/ \-/ \-/
121 ^ ^ ^
122 | | | 1Mbps/10ms delay
123 v v v
124 /-\ /-\ /-\
125 | |<-------->| |<------->| |
126 \-/ \-/ \-/
127 ^ ^ ^
128 | | |
129 v v v
130 /-\ /-\ /--------\
131 | |<-------->| |<---->|Producer|
132 \-/ \-/ \--------/
Alexander Afanasyev6dbacda2012-10-23 17:20:18 -0700133
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -0800134.. literalinclude:: ../../examples/ndn-grid-topo-plugin.cc
135 :language: c++
136 :linenos:
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800137 :lines: 20-26,51-
138 :emphasize-lines: 14-16,20,27-30
Alexander Afanasyev6dbacda2012-10-23 17:20:18 -0700139
140As you can see, scenario code became more compact and more readable.
141
142:ndnsim:`AnnotatedTopologyReader` provides two ways to access topology nodes.
143First, you can use the method :ndnsim:`AnnotatedTopologyReader::GetNodes` which returns NodeContainer.
144
145Alternatively, nodes can be accessed by name using `Names::Find<Node> ("nodename")` call, as in the above example.
146For this purpose,:ndnsim:`AnnotatedTopologyReader` automatically registers all created nodes with names specified in topology file.
147For more information about `Names` class, please refer to `NS-3 documentation <.. http://www.nsnam.org/doxygen/classns3_1_1_names.html>`_
148.
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -0800149
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800150If 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.cc``, you can run and see progress of the simulation using the following command (in optimized mode nothing will be printed out)::
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -0800151
152 NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-grid-topo-plugin
153
154
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -08001556-node bottleneck topology
156--------------------------
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -0800157
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800158This scenario (``ndn-congestion-topo-plugin.cc``) can be used for congestion-related scenarios
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -0800159
160.. aafig::
161 :aspect: 60
162 :scale: 120
163
164 /------\ /------\
165 | Src1 |<--+ +-->| Dst1 |
166 \------/ \ / \------/
167 \ /
168 +-->/------\ "bottleneck" /------\<-+
169 | Rtr1 |<===============>| Rtr2 |
170 +-->\------/ \------/<-+
171 / \
172 /------\ / \ /------\
173 | Src2 |<--+ +-->| Dst2 |
174 \------/ \------/
175
176.. literalinclude:: ../../examples/topologies/topo-6-node.txt
177 :language: bash
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800178 :linenos:
Alexander Afanasyeve97c6072012-11-21 23:51:12 -0800179 :lines: 1-2,15-
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -0800180 :emphasize-lines: 3,13
181
182.. literalinclude:: ../../examples/ndn-congestion-topo-plugin.cc
183 :language: c++
184 :linenos:
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800185 :lines: 20-26,47-
186 :emphasize-lines: 15,21-22,29-34,41-47,52-62
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -0800187
188.. :lines: 20-25,53-
Alexander Afanasyeve97c6072012-11-21 23:51:12 -0800189
190To run this scenario and see what is happening, use the following command::
191
192 NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-congestion-topo-plugin
193
194.. _11-node 2-bottleneck topology with custom forwarding strategy:
195
19611-node 2-bottleneck topology with custom forwarding strategy
197-------------------------------------------------------------
198
199To effectively use the example :ref:`custom strategy <Writing your own custom strategy>`, we need to make sure that FIB entries contain at least two entries.
200In the current version of ndnSIM, this can be accomplished using manual route configuration.
201
202The following example illustrates how the strategy can be used in simulation scenario.
203
204Let us first define a meaningful topology:
205
206.. aafig::
207 :aspect: 60
208 :scale: 120
209
210 /------\ 0 0 /------\
211 | c1 |<-----+ +----->| p1 |
212 \------/ \ / \------/
213 \ /-----\ /
214 /------\ 0 \ +==>| r12 |<==+ / 0 /------\
215 | c2 |<--+ \ / \-----/ \ / +-->| p2 |
216 \------/ \ \ | | / / \------/
217 \ | | 1Mbps links | | /
218 \ 1 v0 v5 1v 2v 3 /
219 +->/------\ /------\<-+
220 2| r1 |<===============>| r2 |4
221 +->\------/4 0\------/<-+
222 / 3^ ^5 \
223 / | | \
224 /------\ 0 / / \ \ 0 /------\
225 | c3 |<--+ / \ +-->| p3 |
226 \------/ / \ \------/
227 / "All consumer-router and" \
228 /------\ 0 / "router-producer links are" \ 0 /------\
229 | c4 |<-----+ "10Mbps" +---->| p4 |
230 \------/ \------/
231
232 "Numbers near nodes denote face IDs. Face ID is assigned based on the order of link"
233 "definitions in the topology file"
234
235The corresponding topology file (``topo-11-node-two-bottlenecks.txt``):
236
237.. literalinclude:: ../../examples/topologies/topo-11-node-two-bottlenecks.txt
238 :language: bash
239 :linenos:
240 :lines: 1-2,28-
241
242Example simulation (``ndn-congestion-alt-topo-plugin.cc``) scenario that utilizes CustomStrategy forwarding strategy:
243
244.. literalinclude:: ../../examples/ndn-congestion-alt-topo-plugin.cc
245 :language: c++
246 :linenos:
247 :lines: 21-28,61-
248 :emphasize-lines: 16,21,49-50,65-79
249
250
251To run this scenario and see what is happening, use the following command::
252
253 NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-congestion-alt-topo-plugin
254
255You can also run using visualizer module to verify that both bottleneck links are utilized::
256
257 ./waf --run=ndn-congestion-alt-topo-plugin --visualize
Alexander Afanasyev59314802012-11-26 14:56:04 -0800258
259.. _trace example:
260
Alexander Afanasyevf4a03592012-12-10 16:12:34 -08002613-level binary tree with packet-level trace helpers
262---------------------------------------------------
Alexander Afanasyev59314802012-11-26 14:56:04 -0800263
264This example (``ndn-tree-tracers.cc``) demonstrates basic usage of :ref:`trace classes`.
265
266In this scenario we will use a tree-like topology, where consumers are installed on leaf nodes and producer is in the root of the tree:
267
268.. aafig::
269 :aspect: 60
270 :scale: 120
271
272 /--------\ /--------\ /--------\ /--------\
273 |"leaf-1"| |"leaf-2"| |"leaf-3"| |"leaf-4"|
274 \--------/ \--------/ \--------/ \--------/
275 ^ ^ ^ ^
276 | | | |
277 \ / \ /
278 \ / \ / 10Mbps / 1ms
279 \ / \ /
280 | | | |
281 v v v v
282 /-------\ /-------\
283 |"rtr-1"| |"rtr-2"|
284 \-------/ \-------/
285 ^ ^
286 | |
287 \ / 10 Mpbs / 1ms
288 +--------\ /--------+
289 | |
290 v v
291 /--------\
292 | "root" |
293 \--------/
294
295The corresponding topology file (``topo-tree.txt``):
296
297.. literalinclude:: ../../examples/topologies/topo-tree.txt
298 :language: bash
299 :linenos:
300 :lines: 1-2,27-
301
302Example simulation (``ndn-tree-tracers.cc``) scenario that utilizes trace helpers:
303
304.. literalinclude:: ../../examples/ndn-tree-tracers.cc
305 :language: c++
306 :linenos:
307 :lines: 21-34,67-
308 :emphasize-lines: 7-11,63-67
309
310
311To run this scenario, use the following command::
312
313 ./waf --run=ndn-tree-tracers
314
315The successful run will create ``rate-trace.txt`` and ``aggregate-trace.txt`` files in the current directly, which can be analyzed manually or used as input to some graph/stats packages.
316
317For example, the following `R script <http://www.r-project.org/>`_ will build a number of nice graphs:
318
319.. image:: _static/root-rates.png
320 :alt: Interest/Data packet rates at the root node
321 :align: right
322
323.. image:: _static/root-5sec-counts.png
324 :alt: Interest/Data packet counts at the root node in 5-second intervals
325 :align: right
326
327.. literalinclude:: ../../examples/graphs/rate-graph.R
328 :language: r
329 :linenos:
330
331For more information about R and ggplot2, please refer to `R language manual <http://cran.r-project.org/manuals.html>`_, `ggplot2 module manual <http://docs.ggplot2.org/current/>`_.
Alexander Afanasyevf4a03592012-12-10 16:12:34 -0800332
333
334
335.. _cs trace helper example:
336
3373-level binary tree with content store trace helper
338---------------------------------------------------
339
340This example (``ndn-tree-cs-tracers.cc``) demonstrates basic usage of :ref:`content store tracer helper class<cs trace helper>`.
341
342In this scenario we will use the same tree-like topology as in :ref:`previous example <trace example>`, where consumers are installed on leaf nodes and producer is in the root of the tree.
343The main difference is that each client request data from the same namespace: /root/1, /root/2, ... Another small difference is that in this scenario we start our application not at the same time, but 10 ms apart.
344
345Example simulation (``ndn-tree-cs-tracers.cc``) scenario that utilizes trace helpers:
346
347.. literalinclude:: ../../examples/ndn-tree-cs-tracers.cc
348 :language: c++
349 :linenos:
350 :lines: 21-31,64-
351 :emphasize-lines: 7-11,25,46,48,65-66
352
353
354To run this scenario, use the following command::
355
356 ./waf --run=ndn-tree-cs-tracers
357
358The successful run will create ``cs-trace.txt``, which similarly to trace file from the :ref:`previous example <trace example>` can be analyzed manually or used as input to some graph/stats packages.
359
Alexander Afanasyev71278d42012-12-12 19:16:54 -08003603-node topology with Content Store respecting freshness field of ContentObjects
361-------------------------------------------------------------------------------
362
363:ref:`Content Store respecting freshness field of ContentObjects`
364
3651-node topology with custom application
366---------------------------------------
367
368:ref:`Custom applications`
369