ns-3 Manual
Release ns-3.26
ns-3 project
October 04, 2016
CONTENTS
1 Contents
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
1.1 Organization .
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2
Random Variables
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3 Hash Functions .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
1.4
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
1.5
.
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6 Object model .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
1.8 Object names .
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
1.9
Logging .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
1.10 Tracing .
.
.
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.11 Data Collection .
.
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.12 Statistical Framework .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
1.13 RealTime .
1.14 Helpers .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
1.15 Making Plots using the Gnuplot Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.16 Using Python to Run ns-3 .
.
1.17 Tests
.
1.18 Support .
.
3
3
4
9
11
13
22
26
43
43
48
64
89
97
99
99
.
. 107
.
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
. . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . .
. . . . .
. . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Events and Simulator .
.
Callbacks .
.
.
.
.
.
.
.
Configuration and Attributes .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2 Source
Bibliography
Index
157
159
161
i
ii
ns-3 Manual, Release ns-3.26
This is the ns-3 Manual. Primary documentation for the ns-3 project is available in five forms:
• ns-3 Doxygen: Documentation of the public APIs of the simulator
• Tutorial, Manual (this document), and Model Library for the latest release and development tree
• ns-3 wiki
CONTENTS
1
ns-3 Manual, Release ns-3.26
2
CONTENTS
CHAPTER
ONE
CONTENTS
1.1 Organization
This chapter describes the overall ns-3 software organization and the corresponding organization of this manual.
ns-3 is a discrete-event network simulator in which the simulation core and models are implemented in C++. ns-3 is
built as a library which may be statically or dynamically linked to a C++ main program that defines the simulation
topology and starts the simulator. ns-3 also exports nearly all of its API to Python, allowing Python programs to import
an “ns3” module in much the same way as the ns-3 library is linked by executables in C++.
Figure 1.1: Software organization of ns-3
The source code for ns-3 is mostly organized in the src directory and can be described by the diagram in Software
organization of ns-3. We will work our way from the bottom up; in general, modules only have dependencies on
modules beneath them in the figure.
We first describe the core of the simulator; those components that are common across all protocol, hardware, and
environmental models. The simulation core is implemented in src/core. Packets are fundamental objects in a
network simulator and are implemented in src/network. These two simulation modules by themselves are intended
to comprise a generic simulation core that can be used by different kinds of networks, not just Internet-based networks.
The above modules of ns-3 are independent of specific network and device models, which are covered in subsequent
parts of this manual.
In addition to the above ns-3 core, we introduce, also in the initial portion of the manual, two other modules that
supplement the core C++-based API. ns-3 programs may access all of the API directly or may make use of a so-called
helper API that provides convenient wrappers or encapsulation of low-level API calls. The fact that ns-3 programs
3
ns-3 Manual, Release ns-3.26
can be written to two APIs (or a combination thereof) is a fundamental aspect of the simulator. We also describe how
Python is supported in ns-3 before moving onto specific models of relevance to network simulation.
The remainder of the manual is focused on documenting the models and supporting capabilities. The next part focuses
on two fundamental objects in ns-3:
the Node and NetDevice. Two special NetDevice types are designed to
support network emulation use cases, and emulation is described next. The following chapter is devoted to Internet-
related models, including the sockets API used by Internet applications. The next chapter covers applications, and the
following chapter describes additional support for simulation, such as animators and statistics.
The project maintains a separate manual devoted to testing and validation of ns-3 code (see the ns-3 Testing and
Validation manual).
1.2 Random Variables
ns-3 contains a built-in pseudo-random number generator (PRNG). It is important for serious users of the simulator to
understand the functionality, configuration, and usage of this PRNG, and to decide whether it is sufficient for his or
her research use.
1.2.1 Quick Overview
ns-3 random numbers are provided via instances of ns3::RandomVariableStream.
• by default, ns-3 simulations use a fixed seed; if there is any randomness in the simulation, each run of the
program will yield identical results unless the seed and/or run number is changed.
• in ns-3.3 and earlier, ns-3 simulations used a random seed by default; this marks a change in policy starting with
ns-3.4.
• in ns-3.14 and earlier, ns-3 simulations used a different wrapper class called ns3::RandomVariable. As of
ns-3.15, this class has been replaced by ns3::RandomVariableStream; the underlying pseudo-random
number generator has not changed.
• to obtain randomness across multiple simulation runs, you must either set the seed differently or set the run
number differently. To set a seed, call ns3::RngSeedManager::SetSeed() at the beginning of the pro-
gram; to set a run number with the same seed, call ns3::RngSeedManager::SetRun() at the beginning
of the program; see Creating random variables.
• each RandomVariableStream used in ns-3 has a virtual random number generator associated with it; all random
variables use either a fixed or random seed based on the use of the global seed (previous bullet);
• if you intend to perform multiple runs of the same scenario, with different random numbers, please be sure to
read the section on how to perform independent replications: Creating random variables.
Read further for more explanation about the random number facility for ns-3.
1.2.2 Background
Simulations use a lot of random numbers; one study found that most network simulations spend as much as 50% of
the CPU generating random numbers. Simulation users need to be concerned with the quality of the (pseudo) random
numbers and the independence between different streams of random numbers.
Users need to be concerned with a few issues, such as:
• the seeding of the random number generator and whether a simulation outcome is deterministic or not,
• how to acquire different streams of random numbers that are independent from one another, and
4
Chapter 1. Contents