Network Simulator (NS2)


NS-MIRACLE: Multi-InteRfAce Cross-Layer Extension library for the Network Simulator

NS-MIRACLE is a set of libraries designed to enhance the functionalities provided by the Network Simulator ns2. It provides an efficient and embedded engine for handling cross-layer messages and, at the same time, enables the coexistance of multiple modules within each layer of the protocol stack. For instance, multiple IP, link layers, MACs or physical layers can be specified and used within the same node. The NS-MIRACLE framework facilitates the implementation and the simulation of modern communication systems in ns2; moreover, due to its modularity, the code will be portable, re-usable and extensible.


  • the nsmiracle howto is probably the best place to start for people willing to use nsmiracle in their project
  • the nsmiracle doxygen documentation is the documentation generated from the comments in the source code, which is an useful reference when developing code using nsmiracle
  • this version of the nsmiracle/mini-HowTo, provides a guide for the installation of nsmiracle over ns 2.33 or higher; please note that dei80211mr libraries are already included in the standard ns distribution from version 2.33
  • the nsmiracle/dei80211mr mini-HowTo, ( although outdated ), still provides some useful tips for the installation of nsmiracle, especially for versions of ns <= 2.32 (this does not apply to versions 2.33 or higher) , for which the patch for dynamic libraries needs be applied

Credits: SIGNET lab: Nicola Baldo, Federico Guerra, Federico Maguolo, Andrea Mior, Marco Miozzo, Michele Rossi

Contact info: For contacts, please refer to the nsmiracle-users mailing list.

NS-MIRACLE development: NS-MIRACLE is being actively maintained and enhanced both by people in our department and by external contributors. The NS-MIRACLE codebase is kept on a subversion repository hosted by our department.

How to download NS-MIRACLE: The latest version of nsmiracle is available at this URL:

The above mentioned subversion repository provides read-only access for guest users using the following account:

username: nsmiracle-dev-guest
password: nsmiracleguest

As an example, using the svn command line client you can check out the latest development version using the guest account by typing the following command:

svn co --username nsmiracle-dev-guest --password nsmiracleguest

We will also be glad to provide read-write accounts to developers who make repeated contributions to nsmiracle.

Finally, we provide a dedicated mailing list (nsmiracle-developers) for the discussions on the development of the code in the nsmiracle repository (subscribe here to the nsmiracle-developers mailing list ).


DESERT Underwater: an NS-Miracle-based framework to DEsign, Simulate, Emulate and Realize Test-beds for Underwater network protocols

DESERT Underwater is a complete set of public C++ libraries that extend the NS-Miracle simulator to support the design and implementation of underwater network protocols. Its creation stems from the will to push the studies on underwater networking beyond simulations. Implementing research solutions on actual devices, in fact, is of key importance to realize a communication and networking architecture that allows heterogeneous nodes to communicate reliably in the underwater environment.
See also the paper describing the library set.

The libraries can be downloaded from the DESERT Underwater web site.

DESERT Underwater v1.0.0 contains the following modules:

  • our implementation of four MAC protocols (CSMA-Aloha, DACAP, Tone-Lohi, UW-Polling) plus a plain version of Aloha;

  • USR, an error-controlled CSMA-Aloha version that uses selective repeat for static and mobile networks;

  • three routing modules (static routing, source routing for underwater networks (SUN), and our implementation of the Information-Carrying Based Routing (ICRP) protocol);

  • two transport modules, including end-to-end error control functions;

  • two application-level modules (for constant and variable bit rate traffic generation);

  • several mobility models for 3D underwater networks;

  • a module to interface the NS-Miracle simulator with acoustic modem hardware; this solution makes it possible to prototype protocols in real deployments, instead of just simulating them.


World Ocean Simulation System (WOSS)

WOSS is a multi-threaded framework that permits the integration of underwater channel simulation tools with network simulators. The present version hinges on Bellhop for computing acoustic propagation in terms of power-delay profiles, and feeds this data into the network simulator NS-Miracle, where physical-layer data are employed for providing a model of link performance.

WOSS provides a set of APIs to automatically feed Bellhop (or other propagation simulators) with all required environmental data (SSPs, bathymetry, bottom sediment geoacoustic coefficients, etc.), so that the user of the network simulator only has to specify the geographical location where the simulated network is operating.

Presently, WOSS takes the required environmental data from the following databases:

The WOSS library is available at the following URL:

Credits: Federico Guerra


dei80211mr: an enhanced 802.11 implementation for ns2 and nsmiracle

The dei80211mr library – nicknamed ‘multirate’ for short – provides a 802.11 implementation for the Network Simulator Version 2. This implementations is derived from the 802.11 implementation included in NS 2.29 and aims at solving some known bugs as well as providing enhanced functionality.

The dei80211mr can be used with NS-Miracle as well as with the original ns2. A release of dei80211mr is included as part of official ns-allinone releases from version 2.33 above.

The following functionalities are provided by the dei80211mr library:

  • support for multiple PHY modes is included; in particolar, dei80211mr simulation of the different transmission rates, modulation and coding schemes defined in the IEEE802.11b/g standards.
  • a SINR-based packet level error model is introduced:
    • the RX Threshold variable which was used in the 802.11 implementation included in standard NS to determine successful receptions has been removed. Instead, Packet Error Rate (PER) is used to determine random packet losses.
    • PER is calculated using pre-determined curves (PER vs SINR and packet size); the curves can be specified by the user via TCL. Some default curves for both 802.11g and 802.11b are provided.
    • SINR is calculated using received signal strength, noise and interference
    • interference is calculated using a gaussian model to account for all transmissions which happen simultaneously to the one which is considered for reception
    • noise power is set via TCL
  • the capture model, i.e. the determination of whether a packet can be received when there are other concurrent transmissions are simultaneously ogoing, is now embedded in the above mentioned interference model (no more Capture Threshold)
  • Some well-known bugs of the 802.11 implementation in NS have been resolved. With reference to [1], we solved the following bugs:
    • direct access denial
    • random backoff time
    • capture model (note: this is different from the point above since, as per the description in [1], it is actually a synchronization issue)
  • In the wireless channel, the affected nodes distance is no more determined using the CS threshold, but we used a fixed value in meters (distInterference_) which can be set at the beginning of the simulation. The reason is that, since we use a gaussian interference model, nodes well below the CS threshold often still provide a non-negligible contribution to interference. The default value for the affected nodes distance (distInterference_) is very conservative, so that all nodes are considered for interference calculation. This default value therefore yields accurate but computationally intensive simulations. The value can be adjusted via TCL to achieve different trade-offs between computational load and simulation accuracy.

Credits: SIGNET lab: Federico Maguolo, Nicola Baldo, Simone Merlin, TS lab: Matteo Trivellato

Download dei80211mr

[1] Ilango Purushotaman and Sumit Roy, IEEE802.11 implementation Issues in Network Simulator 2

NS2 Simulation Code for Wireless Network Coding

The package below provides the random network coding modules for ns2.27.

ns2 Simulation Code for Wireless Network Coding

Network coding is a packet delivery scheme for distributed networks. It differs from the classical “receive and forward” paradigm as information packets are encoded at intermediate nodes in the network and subsequently forwarded according to a store, code, and forward approach. The strength of this strategy consists of the coding phase which improves the dissemination efficiency and reduces the number of transmissions required to deliver the data. Although network coding schemes require some data processing at intermediate nodes to code/decode packets, it has been proven that simple coding operations, e.g., linear coding, are sufficient to achieve close to optimal performance. Installation instructions and copyright notice are included in the above package.


A patch for effectively using Dynamic Libraries in NS-2

NOTE: this patch has been integrated in the official ns2 distribution since release 2.33; therefore, only users of older versions of ns2 need to apply the patch.

Description: the introduction of dynamically loadable modules significantly improves the way of developing extensions to ns by achieving the following objectives:

1. enabling people to develop add-ons for ns2 (e.g. introducing new agents, packet types, protocols) without having to modify ns2 itself
2. allowing dynamic loading of different modules at simulation time, without having to recompile the whole ns or keep different ns binaries
3. making installation of third-party modules easier, thereby enhancing the dissemination of the many valuable ns2 modules developed around the world
4. making life easier for lab technicians and students: an official ns2 version can be installed by the administrators, and students can just build and use their preferred modules independently.
5. helping making ns2 more modular and scalable, while keeping backward compatibility.

Documentation: please refer to the dynamic libraries documentation

Credits: SIGNET lab: Nicola Baldo, Federico Maguolo, Marco Miozzo, Michele Rossi

Download the patch for ns-2.29 or ns-2.31


NS-Miracle Sandbox library

Type: NS-Miracle Add-on

Description: We also provide a sample library which we call the Sandbox. The set of modules included in the Sandbox library provides a didactical cross-layer architecture which illustrates how cross-layer interactions can be implemented within NS-Miracle. The name Sandbox is meant to encourage developers to get their hands dirty with the code and try to implement their own cross-layer interactions. The Sandbox is a completely separate library so there is no risk of compromising your existing NS-Miracle installation.

Credits: SIGNET lab: Nicola Baldo, Federico Maguolo, Marco Miozzo, Michele Rossi

Download Download Now


Monologue for ns-miracle

Type: NS-Miracle add-on

Description: This module is an implementation of a two state Time Continuous Semi-Markov Process, described in the early sections of [1]. This model has two states: silence and speech with two distinct probability distributions. To set up a monologue or an uncorrelated conversation two instances of monologue-1.0 are still needed because we still need a receiver of the same type. The model also implements a VAD (Voice activity detector) and a fillin and an hangover mode.

Download Download Now


Conversation for ns-miracle

Type: NS-Miracle add-on

Description: This modules is an implementation of a complex mathematical model suited to simulate a conversation, better known as the Stern Model [1]. It is basically an eight state Continuous Markov Chain that controls the behavior of both interlocutors. To achieve such correlation between the two peer applications a master-slave archetype has been used. The model also implements a VAD (Voice activity detector) and a fill-in and an hangover mode.

Download: Download Now


Video for ns-miracle

Type: NS-Miracle add-on

Description: This module provides a framework for the evaluation of the quality of service of video communications in ns-miracle. This module interacts with existing video codecs (ffmpeg) and video evaluation tools (evalvid) in order to simulate the transmission of video streams and evaluate performance metrics such as PSNR and MOS at the receiver.

Download Download Now



Type: NS-Miracle add-on

Description: This module provides Forward Error Correction functionality for CBR applications, according to RFC 2733 An RTP Payload Format for Generic Forward Error Correction. The FEC encoder provides three different coding schemes (respectively, 1/2, 2/3, and 24/35). The FEC decoder uses Gaussian elimination to be able to decode arbitrarily coded packet streams.

Download Download Now


[1] H.P. Stern, S.A. Mahmoud and K.K. Wong, A comprehensive model for voice activity in conversational speech-development and application to performance analysis of new-generation wireless communication systems, in Wireless Networks, Springer, 1996