|
1 .. include:: replace.txt |
|
2 |
|
3 Introduction |
|
4 ------------ |
|
5 |
|
6 The |ns3| simulator is a discrete-event network simulator targeted |
|
7 primarily for research and educational use. The |
|
8 `ns-3 project |
|
9 <http://www.nsnam.org>`_, |
|
10 started in 2006, is an open-source project developing |ns3|. |
|
11 |
|
12 Primary documentation for the |ns3| project is available in four |
|
13 forms: |
|
14 |
|
15 * `ns-3 Doxygen/Manual |
|
16 <http://www.nsnam.org/doxygen/index.html>`_: |
|
17 Documentation of the public APIs of the simulator |
|
18 * Tutorial (this document) |
|
19 * `Reference Manual |
|
20 <http://www.nsnam.org/docs/manual.html>`_: Reference Manual |
|
21 * `ns-3 wiki |
|
22 <http://www.nsnam.org/wiki/index.php>`_ |
|
23 |
|
24 The purpose of this tutorial is to introduce new |ns3| users to the |
|
25 system in a structured way. It is sometimes difficult for new users to |
|
26 glean essential information from detailed manuals and to convert this |
|
27 information into working simulations. In this tutorial, we will build |
|
28 several example simulations, introducing and explaining key concepts and |
|
29 features as we go. |
|
30 |
|
31 As the tutorial unfolds, we will introduce the full |ns3| documentation |
|
32 and provide pointers to source code for those interested in delving deeper |
|
33 into the workings of the system. |
|
34 |
|
35 A few key points are worth noting at the onset: |
|
36 |
|
37 * Ns-3 is not an extension of `ns-2 |
|
38 <http://www.isi.edu/nsnam/ns>`_; |
|
39 it is a new simulator. The two simulators are both written in C++ but |
|
40 |ns3| is a new simulator that does not support the ns-2 APIs. Some |
|
41 models from ns-2 have already been ported from ns-2 to |ns3|. The |
|
42 project will continue to maintain ns-2 while |ns3| is being built, |
|
43 and will study transition and integration mechanisms. |
|
44 * |ns3| is open-source, and the project strives to maintain an |
|
45 open environment for researchers to contribute and share their software. |
|
46 |
|
47 |
|
48 For ns-2 Users |
|
49 ************** |
|
50 |
|
51 For those familiar with ns-2, the most visible outward change when moving to |
|
52 |ns3| is the choice of scripting language. Ns-2 is |
|
53 scripted in OTcl and results of simulations can be visualized using the |
|
54 Network Animator nam. It is not possible to run a simulation |
|
55 in ns-2 purely from C++ (i.e., as a main() program without any OTcl). |
|
56 Moreover, some components of ns-2 are written in C++ and others in OTcl. |
|
57 In |ns3|, the simulator is written entirely in C++, with optional |
|
58 Python bindings. Simulation scripts can therefore be written in C++ |
|
59 or in Python. The results of some simulations can be visualized by |
|
60 nam, but new animators are under development. Since |ns3| |
|
61 generates pcap packet trace files, other utilities can be used to |
|
62 analyze traces as well. |
|
63 In this tutorial, we will first concentrate on scripting |
|
64 directly in C++ and interpreting results via trace files. |
|
65 |
|
66 But there are similarities as well (both, for example, are based on C++ |
|
67 objects, and some code from ns-2 has already been ported to |ns3|). |
|
68 We will try to highlight differences between ns-2 and |ns3| |
|
69 as we proceed in this tutorial. |
|
70 |
|
71 A question that we often hear is "Should I still use ns-2 or move to |
|
72 |ns3|?" The answer is that it depends. |ns3| does not have |
|
73 all of the models that ns-2 currently has, but on the other hand, |ns3| |
|
74 does have new capabilities (such as handling multiple interfaces on nodes |
|
75 correctly, use of IP addressing and more alignment with Internet |
|
76 protocols and designs, more detailed 802.11 models, etc.). ns-2 |
|
77 models can usually be ported to |ns3| (a porting guide is under |
|
78 development). There is active development on multiple fronts for |
|
79 |ns3|. The |ns3| developers believe (and certain early users |
|
80 have proven) that |ns3| is ready for active use, and should be an |
|
81 attractive alternative for users looking to start new simulation projects. |
|
82 |
|
83 Contributing |
|
84 ************ |
|
85 |
|
86 |ns3| is a research and educational simulator, by and for the |
|
87 research community. It will rely on the ongoing contributions of the |
|
88 community to develop new models, debug or maintain existing ones, and share |
|
89 results. There are a few policies that we hope will encourage people to |
|
90 contribute to |ns3| like they have for ns-2: |
|
91 |
|
92 * Open source licensing based on GNU GPLv2 compatibility; |
|
93 * `wiki |
|
94 <http://www.nsnam.org/wiki/index.php>`_; |
|
95 * `Contributed Code |
|
96 <http://www.nsnam.org/wiki/index.php/Contributed_Code>`_ page, similar to ns-2's popular Contributed Code |
|
97 `page |
|
98 <http://nsnam.isi.edu/nsnam/index.php/Contributed_Code>`_; |
|
99 * ``src/contrib`` directory (we will host your contributed code); |
|
100 * Open `bug tracker |
|
101 <http://www.nsnam.org/bugzilla>`_; |
|
102 * |ns3| developers will gladly help potential contributors to get |
|
103 started with the simulator (please contact `one of us |
|
104 <http://www.nsnam.org/people.html>`_). |
|
105 |
|
106 We realize that if you are reading this document, contributing back to |
|
107 the project is probably not your foremost concern at this point, but |
|
108 we want you to be aware that contributing is in the spirit of the project and |
|
109 that even the act of dropping us a note about your early experience |
|
110 with |ns3| (e.g. "this tutorial section was not clear..."), |
|
111 reports of stale documentation, etc. are much appreciated. |
|
112 |
|
113 Tutorial Organization |
|
114 ********************* |
|
115 |
|
116 The tutorial assumes that new users might initially follow a path such as the |
|
117 following: |
|
118 |
|
119 * Try to download and build a copy; |
|
120 * Try to run a few sample programs; |
|
121 * Look at simulation output, and try to adjust it. |
|
122 |
|
123 As a result, we have tried to organize the tutorial along the above |
|
124 broad sequences of events. |
|
125 |