Introduction to NS-3

Konstantinos Katsaros
k.katsaros @ surrey.ac.uk

Centre for Communications System Research

University of Surrey

System Level Simulations - Technical Club

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

Outline

1 Introduction

2 NS-3 Modules

3 LTE Module

4 WiFi Example

K. Katsaros Introduction to NS-3 04/07/13 2 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Introduction

ns-3 is written in C++, with bindings available for Python

simulation programs are C++ executables or Python programs
∼300,000 lines of mostly C++ (estimate based on cloc source code
analysis)
ns-3 is a GNU GPLv2-licensed project
ns-3 is mainly supported for Linux, OS X, and FreeBSD
ns-3 is not backwards-compatible with ns-2

K. Katsaros Introduction to NS-3 04/07/13 3 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Where to get it

Where do I get ns-3?

- http://www.nsnam.org
Where do I get today’s code?
Download the latest release:
- wget
http://www.nsnam.org/releases/ns-allinone-3.17.tar.bz2
- tar xjf ns-allinone-3.17.tar.bz2
Clone the latest development code1 :
- hg clone http://code.nsnam.org/ns-3-allinone

1 Mercurial is used as source code control tool

K. Katsaros Introduction to NS-3 04/07/13 4 / 33
Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Current Modules in main NS-3 tree

Network: Node, Sockets, Queues, Packet, etc

Core: Smart Pointers, Callbacks, Event, Scheduler, Logging, Tracing, etc

K. Katsaros Introduction to NS-3 04/07/13 5 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Module Organization

model/ ← contains source code for main part of module

helper/ ← contains code for helper classes
examples/
tests/
bindings/ ← files related to python
doc/
wscript ← the “Makefile" equivalent

K. Katsaros Introduction to NS-3 04/07/13 6 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Helper API

The ns-3 “helper API" provides a set of classes and methods that
make common operations easier than using the low-level API
Consists of:
- container objects
- helper classes
The helper API is implemented using the low-level API
Users are encouraged to contribute or propose improvements to the
ns-3 helper API

K. Katsaros Introduction to NS-3 04/07/13 7 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Building NS-3

Waf is a Python-based framework for configuring, compiling and

installing applications.
It is a replacement for other tools such as Autotools, CMake or Ant
http://code.google.com/p/waf/
For those familiar with autotools:
configure → ./waf configure
make →./waf build

K. Katsaros Introduction to NS-3 04/07/13 8 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Discrete-event simulations

Simulation time moves in discrete jumps from event to event

C++ functions schedule events to occur at specific simulation times
A simulation scheduler orders the event execution
Simulator::Run() gets it all started
Simulation stops at specific time or when events end

K. Katsaros Introduction to NS-3 04/07/13 9 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Time in NS-3

Time is stored as a large integer in ns-3

- Avoid floating point discrepancies across platforms
Special Time classes are provided to manipulate time (such as
standard operators)
Default time resolution is nanoseconds, but can be set to other
resolutions
Time objects can be set by floating-point values and can export
floating-point:
double timeDouble = t.GetSeconds();

K. Katsaros Introduction to NS-3 04/07/13 10 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
NS-3 API

Most of the ns-3 API is documented with Doxygen

(http://www.doxygen.org/)

K. Katsaros Introduction to NS-3 04/07/13 11 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Scalability

Distributed simulation in ns-3 allows a user to run a single

simulation in parallel on multiple processors
By assigning a different rank to nodes and connecting these nodes
with point-to-point links, simulator boundaries are created
Simulator boundaries divide Logical Processes (LPs), and each LP
can be executed by a different processor
Distributed simulation in ns-3 offers solid performance gains in time
of execution for large topologies
Simulation on a HPC cluster at the U.S. Mobile Network Modeling
Institute (2011)2
- 176 cores, 3 TB of memory
- 360,448,000 simulated nodes
- 413,704.52 packet receive events per second [wall-clock]
2 K. Renard et al, “A Performance and Scalability Evaluation of the NS-3

Distributed Scheduler. Proceedings of WNS3 2012

K. Katsaros Introduction to NS-3 04/07/13 12 / 33
Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Attribute System

Problem: Researchers want to identify all of the values affecting the

results of their simulations and configure them easily
ns-3 solution: Each ns-3 object has a set of attributes:
- A name, help text
- A type
- An initial value
Control all simulation parameters for static objects
Dump and read them all in configuration files
Visualize them in a GUI
Makes it easy to verify the parameters of a simulation
List of all attributes in the API:
http://www.nsnam.org/docs/release/3.17/doxygen/group___
attribute_list.html

K. Katsaros Introduction to NS-3 04/07/13 13 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Tracing System

Simulator provides a set of pre-configured trace sources

- Users may edit the core to add their own
Users provide trace sinks and attach to the trace source
-Simulator core provides a few examples for common cases
Multiple trace sources can connect to a trace sink
List of all trace sources in the API:
http://www.nsnam.org/docs/release/3.17/doxygen/group_
__trace_source_list.html

K. Katsaros Introduction to NS-3 04/07/13 14 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
FlowMonitor

Network monitoring framework found in

src/flow-monitor/
Goals:
- detect all flows passing through network
- stores metrics for analysis such as throughput, duration, delays, packet
sizes, packet loss ratios
Currently works ONLY on IPv4 packets.

K. Katsaros Introduction to NS-3 04/07/13 15 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
NetAnim

Animate packets over wired-links and wireless- links

- limited support for LTE traces
Packet timeline with regex filter on packet meta-data.
Node position statistics with node trajectory plotting (path of a
mobile node).
Print brief packet meta-data on packets

K. Katsaros Introduction to NS-3 04/07/13 16 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
LTE module - Design

FemtoForum LTE MAC Scheduler API

Radio signal model granularity: Resource Block
- Symbol-level model not affordable
- Simplified Channel PHY model
Realistic Data Plane Protocol stack model
- Realistic RLC, PDCP, S1-U, X2-U
- Allow proper interaction with IP networking
- Allow end-to-end QoE evaluations
Hybrid Control Plane model:
- Realistic RRC model
- Simplified S1-C, X2-C and S11 models
Simplified EPC
- One MME and one SGW
- SGW and PGW in the same node (no S5/S8 interface)
Focus on connected mode
- RRC connected, EMM Registered, ECM connected
K. Katsaros Introduction to NS-3 04/07/13 17 / 33
Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Model Overview

K. Katsaros Introduction to NS-3 04/07/13 18 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Propagation Models

Buildings model
- Add buildings to network topology
Path loss model
- Okumura Hata (outdoor)
- ITU-R P1411 LOS & NLOS (outdoor)
- ITU-R P1238 (indoor)
- External & internal wall losses
- Log-normal shadowing
- Pathloss logic chooses correct model depending on node position
Fast fading model
- Trace-based
- Freq. and time dependent
Antenna models
- Isotropic
- Sectorial (cosine & parabolic shape)

K. Katsaros Introduction to NS-3 04/07/13 19 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
PHY model

Only FDD is modelled

Freq domain granularity: RB
Time domain granularity: 1 TTI, further divided into
- DL: ctrl, data - UL: ctrl+data, SRS
Gaussian Interference model
CQI feedback
Signal processing not modelled accurately
→ use error model
SISO propagation model
MIMO modeled as SINR gain over SISO
- different gains for different TX modes
Supports different freqs and bandwidths per eNB
- leveraging on the ns-3 Spectrum module

K. Katsaros Introduction to NS-3 04/07/13 20 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
MAC Scheduler model

Resource allocation model:

- allocation type 0
- RBs grouped into RBGs
- localized mapping approach
Adaptive Modulation and Coding
- two algorithms working on reported CQI feedback
- “Piro" model: based on analytical BER (very conservative)
- “Vienna" model: aim at max 10% BLER based on error model
curves
- Dynamic TX mode selection supported
but no adaptive algorithm currently implemented
Transport Block model
- Mimics 3GPP structure
mux RLC PDU onto MAC PDU
- Virtual MAC Headers and CEs (no real bits)
MAC overhead not modeled
Consistent with requirements (scheduler neglects MAC OH)
K. Katsaros Introduction to NS-3 04/07/13 21 / 33
Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
MAC Scheduler

Round Robin (RR)

Proportional Fair (PF)
Maximum Throughput (MT)
Throughput to Average (TTA)
Blind Average Throughput (BET)
Token Bank Fair Queue (TBFQ)
Priority Set Scheduler (PSS)
All implementations based on the FemtoForum API
The above algorithms are for downlink only
For uplink, all current implementations use the same Round Robin
algorithm

K. Katsaros Introduction to NS-3 04/07/13 22 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Simulation Output

Lots of KPIs available at different levels:

Channel
- SINR maps
- pathloss matrices
PHY
- TB tx / rx traces
- RSRP/RSRQ traces
MAC
- UL/DL scheduling traces
RLC and PDCP
- Time-averaged PDU tx / rx stats
IP and application stats
- Can be obtained with usual ns-3 means
- FlowMonitor, PCAP traces, get stats directly from app, etc.

K. Katsaros Introduction to NS-3 04/07/13 23 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Features Highlighted

K. Katsaros Introduction to NS-3 04/07/13 24 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Simulation Time

5s sim time, 1 UE per eNB, full traffic

K. Katsaros Introduction to NS-3 04/07/13 25 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Walkthrough of WiFi Internet example

K. Katsaros Introduction to NS-3 04/07/13 26 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
NS-3 Implementation of WiFi Example

K. Katsaros Introduction to NS-3 04/07/13 27 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Structure of NS-3 program

int main (int argc, char *argv[]) {

// Set default attribute values
// Parse command-line arguments
// Configure the topology; nodes, channels, devices,
mobility
// Add (Internet) stack to nodes
// Configure IP addressing and routing
// Add and configure applications
// Configure tracing
// Run simulation
}

K. Katsaros Introduction to NS-3 04/07/13 28 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Source Code for P2P example

Starting your script with this line ensures that emacs editor will be able
to indent your code correctly. The following lines ensure that your code is
licensed under the GPLv2.
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil;
-*- */
// GPLv2 Licence
Include the proper header files. For simulation scripts, you can aggregate
them with modules, but when developing your module, you have to
include the specific header file (not the aggregated)
include “ns3/core-module.h"
include “ns3/network-module.h"
include “ns3/internet-module.h"
include “ns3/point-to-point-module.h"
include “ns3/applications-module.h"
...
Use the ns3 project namespace
using namespace ns3;
K. Katsaros Introduction to NS-3 04/07/13 29 / 33
Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
example cont.

Enable and disable console message logging by reference to the name

NS_LOG_COMPONENT_DEFINE (“FirstScriptExample");
int main (int argc, char *argv[])
LogComponentEnable (“UdpEchoClientApplication", LOG_LEVEL_INFO);
LogComponentEnable (“UdpEchoServerApplication", LOG_LEVEL_INFO);
Topology Configuration
NodeContainer nodes;
nodes.Create (2);
PointToPointHelper pointToPoint;
pointToPoint.SetDeviceAttribute ("DataRate", StringValue
("5Mbps"));
pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));
NetDeviceContainer devices;
devices = pointToPoint.Install (nodes);

K. Katsaros Introduction to NS-3 04/07/13 30 / 33

Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
example cont.

Set up Internet Stack

InternetStackHelper stack;
stack.Install (nodes);
Ipv4AddressHelper address;
address.SetBase ("10.1.1.0", "255.255.255.0");
Ipv4InterfaceContainer interfaces = address.Assign (devices);
Set up applications
UdpEchoServerHelper echoServer (9);
ApplicationContainer serverApps = echoServer.Install (nodes.Get (1));
serverApps.Start (Seconds (1.0));
serverApps.Stop (Seconds (10.0));
UdpEchoClientHelper echoClient (interfaces.GetAddress (1), 9);
echoClient.SetAttribute ("MaxPackets", UintegerValue (1));
echoClient.SetAttribute ("Interval", TimeValue (Seconds (1.0)));
echoClient.SetAttribute ("PacketSize", UintegerValue (1024));
ApplicationContainer clientApps = echoClient.Install (nodes.Get (0));
clientApps.Start (Seconds (2.0));
clientApps.Stop (Seconds (10.0));
Run your scenario
Simulator::Run ();
Simulator::Destroy ();
K. Katsaros Introduction to NS-3 04/07/13 31 / 33
Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Resources

Web site:
http://www.nsnam.org
Mailing list:
https://groups.google.com/forum/?fromgroups#!forum/
ns-3-users
IRC:
ns-3 at freenode.net
Tutorial:
http://www.nsnam.org/docs/tutorial/tutorial.html
Code server:
http://code.nsnam.org
Wiki:
http://www.nsnam.org/wiki/index.php/Main_Page
For LENA project:
http:
//iptechwiki.cttc.es/LTE-EPC_Network_Simulator_(LENA)
K. Katsaros Introduction to NS-3 04/07/13 32 / 33
Introduction NS-3 Modules LTE Module WiFi Example Acknoledgement

FakeTitle1
Acknowledgments

Special Thanks to:

Tom Henderson
Mathieu Lacage
Nicola Baldo
for borrowing material from their presenations

K. Katsaros Introduction to NS-3 04/07/13 33 / 33