Ns-3-Is it a Network Simulator or Network Simulation Library

I started to discuss problems in understanding ns-3 in the article “What Makes ns-3 a Complex Thing to Understand and Use? “. I received answers and valuable comments from the ns-3 Users and Developers. So, that post/article became a little bit big and its bigness started to reduce the overall readability of that article.

So, I decided to post a separate Article on a very important issue (for me) that was realized during my discussion with experts.

Is ns-3 a Network Simulator or a Network Simulation(/Simulator) Library?

This question is important because, 15 years ago, when I first tried to compile the very first release of ns-3, after compiling it I searched for a simulator.
Because, in my previous experience with open source and non-free simulators, I found one such simulator in them after installing or compiling them.

source – binary
————————————-
ns-2 -> ns
Omnet++ -> omnetpp
Opent -> opnet (? – forgot the name of the binary because, nowadays, I am using only open-source simulators)
… -> …
—————————————-

After compiling ns-3 for the first time, I wasn’t able to find one such simulator to do simulations. It was a great disappointment to me at that time :-)) I was continuously trying to understand the ‘simulator’ in ‘ns-3 code’.
But only after a decade, I realized that the simulation itself becoming the simulator while compiling it. (from my perspective)

That is why this is a serious question here to understand ns-3 (at least for a beginner who had experience with some other simulators)

I hope that the readers will understand the significance of this.

Conventionally, If we compile code, it will generate a binary. The binary is the final product can be called an “Application Software” from the user’s perspective. Because, if it ends up as a “shareable library”, then the final product is only an “Application Library” – not an “Application Software” by itself.

So, for example. in the case of ns-2, if we compile it, then it will create a binary ‘ns’ that binary is the simulator that will run a simulation like

$ ns example.tcl

Here the example.tcl is the simulation script and ns is the simulator that is going to simulate it.

Another example is if we compile the code of NetAnim, we will get a final binary “NetAnim” that can be called as an “Application/Software” from the user’s perspective.

But, I think, in the case of ns-3, you will not have a separate, “runnable” simulator binary – of course, all the compiled components of ns-3 will be in binary form – but not runnable separately as a ‘generic simulator’ as in the case of ns-2’s ‘ns’.

So, if we write a simulation script using ns-3 conventions and using ns-3 library modules, and compile it as follows:

./waf –run example
Then it will compile the simulation script “example.cc” and run the code from the main() function of example.cc.

As per my understanding, the core scheduler itself becomes part of my code example.cc and called from within the binary of example.cc and scheduling the events that are referred in example.cc – since it is only having the entry point main() – am I wrong?

So, from my point of view (or from an end-user perspective), the binary of example.cc is the final product after compilation – so it is the standalone simulator that will run as a separate process and will interpret the lines from within the main() function of it.

That’s why I am understanding each and every binary of my ns-3 simulation scripts as separate versions of a simulator (which are built on the shared libraries of ns-3 modules)

If we do a UWNS simulation using a ns-3 simulation script, then the resultant binary is an UnderwaterNetworkSimulator.
Like that, if we do a VANET simulation in another a ns-3 simulation script, then the resultant binary will become a VANET simulator.

Because we can change the behaviour of these “simulators” by passing different values/parameters through the mechanism basically ns-3 is providing.

Do I miss something here?
Is there any other main() function from which ns-3 is running my compiled binary of example.cc?

Please someone explain it.

Where is the binary of the simulator ns-3; so that it can be called a standalone application? -as in the case of ns-2. (of course, I understand ns-3 is not the next version of ns-2 – an entirely different thing)

The above question is one of my mind-itching questions from the first release of ns-3.
In fact, this question only delayed my practical use of ns-3 for more than 10 years (trust me – it is true).
After abstractly understanding this fact only, I started to use ns-3 without any hesitation.

How ns-3 is different from most of the other simulators?

In most of the popular simulators (except ns-3), the simulator will be a different entity and the simulation script that the user will write for that simulator will be a separate entity. While running the simulation script, the simulator will just run/interpret the lines that the user created.

For example,

Under ns-2, the simulation will be presented in the form of TCL script and the core simulator which is made up of C++ and TCL objects will simply interpret the lines of the TCL simulation script.
Under Omnet ++, the simulation script will be a custom format text file (not like any programming language) core simulator which is made up of C++ objects will simply interpret the lines of the simulation script.
Even most of the non-free simulators are following the same ideology (Simulator is different from simulation script)

If a researcher needs to add a new protocol/application agent (for example in the case of ns-2), then they will write code for that protocol/application agent, by adopting the standards of the core simulator and compiling the core simulator itself with the added new protocol/application agent model. After that, a user can use that new object within their simulations. The simulation script can be modified as per the requirement and can be run without recompiling the core simulator code.

So in other simulators, the simulator will interpret/run the simulation script.

So there will be only one “main()” function through which the core simulator starts running and start interpreting/running the simulation script. No other C++ code module will have “main()” function.Trace Analysis is generally done separately using a scripting language (using scripting languages/ or [advance filters from UNIX perspective] such as tcl, awk, perl, shell etc.,)

Because, while starting to install any “Simulator”, first we try to install it in an easy way; like:

# do not try this – this command will only work in some debian/ubuntu versions,

$ sudo apt-get install ns-3

Because, after installing a software, it will be easy for us to “use” that software and do our simulations without thinking about “compiling” anything again. (like using ns-2 binary only to interpret a simple simulation code in tcl)

Of course, it is technically possible to provide the binary version of ns-3 library in this way – so that a user can directly use it in their simulation without compiling the library again. But the problem here is : the user can not run this own simulation without compiling it.

The following screenshot shows the possible installation of ns3 (libraries) from the Debian repository.

Check the following link for the package information :

https://community.linuxmint.com/software/view/libns3-3v5#

So, (unlike ns-2,) generally, ns-3 needs compilation for running each and every single simulation script that we write (along with the entire source code or precompiled binaries of ns-3 libraries). Of course, ns-2 itself needs recompilation, if the user tries to change some of the files in ns-2 but, we need not recompile it for running a user simulation script that was written in tcl. In other words, if we wrie a simulation script under ns-3, then we have to compile it using the ns-3 libraries.

So as a convention, ns-3 is always provided as a “source” from that one should compile his own simulations using a compiler (by compiling the ns-3 libraries and the user scripts).

So, the problem of “understanding ns-3” even starts at the way in which it is distributed.

Why this question is that much important?

Of course, the official documentation provided for ns-3 is discussing each and every aspect of this software.

But, most of the learners of ns-3 will not have time to understand its magnitude, because, they are simply forced to do a “class assignment” or project or “mini-project” during their undergraduate or postgraduation.

It is impossible for an average student to understand “what is ns-3” by reading the rich official documentation of n-3. The reasons are:

Even though the words/phrases “software”, “application”, “Software Library” and “Application Library” are having distinct meanings, we use them to denote “software entities” according to our knowledge without really understanding the fine difference in them.
All of them those who try to learn ns-3will not be “Natives” of English Speaking countries to grasp that huge official documentation of n-3.
In most countries, ns2/ns3 is not at all taught or even introduced through their curriculum.
99 % of teachers and professors in remote urban areas of most of the growing counties are not at all have fundamental knowledge on a “Network Simulator” or Simulation -but their curricula expect their Undergraduate or Postgraduate students to do a scholarly research work on ns-3 by following an IEEE paper as a reference.
Of course, all such poor, ‘pathetic’ students are managing their project submission in one way or another without understanding anything or at least without understanding ns-3.

So there should be some “idiot’s guide for ns-3” for idiots like me (who used ns-3 for more than 10 years; even without understanding where is the simulator in it)

So, Finaly, what is ns-3?

ns-3 is nothing but a collection of C++ objects of Protocols/Application Agents and the simulation core modules. So the separate code of all of these objects of Protocols/Application Agents and the simulation core modules, will not have “main()” function. So ns-3 is technically a collection of Network Simulation related objects – not a simulator by itself. (please correct me if I am wrong)

So, simply, the simulation script (the C++ code) that we write will have the main() function, which will be the gateway/starting point of the simulator. So, simply, after compiling our code, using all other referred/used modules of ns-3(including the core simulator modules), our code itself gets compiled and will become a new simulator. (please correct me if I am wrong)

Unlike ns-2, what we conventionally call ns-3 is not at all a simulator by itself. The simulation script that we write itself will become a custom simulator or “contain” a simulator in it. So each and every simulation script that we write will become a separate, custom network simulator. (please correct me if I am wrong)

References

Reply/Comments Received at ns-3-users Group

(one may check the original discussion @ ns-3-users Group)

Follow the Opinions and Comments of ns3-users and Developers in green text below

Mr. Gabriel Ferreira Posted the Following Comments on ns-3 User Group

You seem to be confused about the lack of an executable that runs the simulation.

The essential simulator components of ns-3 are in the core library.

It doesn’t have a main, but a start, stop and destroy.

The simulators you mention parse the simulation file and then call essentially their versions of schedule, start, stop and destroy.

So you’re really pointing to a parser of the simulation and not the simulator itself.

You can setup a simulation parser in c++ to read parameters from a json/yaml/TCL file and schedule the appropriate events, compile it and call it ns3. It doesn’t make it a simulator, since it doesn’t implement the simulator components, just call them.

Mr. Tom Henderson Posted the Following Comments on ns-3 User Group

OK, I understand better now where your concern arises. I will try to

update the tutorial to clarify this. Something like:

“Readers may be familiar with other simulators that are compiled into an
executable that is invoked with a second file interpreted by the
simulator and that contains the configuration. For example, in ns-2:

./ns simple.tcl

ns-3 is not compiled into a generic executable that interprets
configuration files, such as the above. Instead, ns-3 is made up of
shared libraries that are later linked to a different executable
(containing configuration) that the user creates. The libraries are
modular and typically can be found in the ‘build/lib’ directory. The
essential library to include is ‘core’ since that has the implementation
of running and stopping the simulator’s event scheduler, but other
libraries can be added depending on the functionality needed. The user
would then write a ‘simple.cc’ program with a main() function and
compile and link it to the necessary ns-3 libraries, and then call the
‘simple’ executable directly. If desired, the ‘simple.cc’ can be
further configured to accept command-line arguments and to read
configuration files so that changes to the parameterization of the
program do not require recompilation and relinking.

In summary, in a simulator like ns-2, the step of running the simulation
such as:

./ns simple.tcl [… optional arguments]

looks like the following in ns-3 (making use of a script named ‘ns3’):

./ns3 –run ‘simple [… optional arguments]’

or when no options are present:

./ns3 –run simple”

What do you think; does it help?

The above explanation is how it is planned to work when we convert to
CMake; with the current code and Waf, one would instead run:

./waf –run simple

– Tom

My Reply To Mr Tom Henderson Posted on ns-3 User Group

Mr. Tom,
As usual, you are the one that correctly understanding the issue and its magnitude.

Strictly speaking, ns-3 is not a standalone network simulator (even though it has everything in it) – is just a state-of-the-art Network Simulator Library.

In fact, I understand what is ns-3 after 10 years of a vague confusion and struggle (because, I really searched for a runnable binary in the default installation).
So, while a simulation script is using this library, after that only a simulator will born.

You may elaborately explain the difference between ns-3 and other simulator. But before doing that, you must simply define it something like the following to avoid any further confusion for people like me.

——————————————-
1) Unlike other simulators, ns-3 is an advanced Simulator/Simulation Library. Because ns-3 doesn’t have a standalone runnable binary. Explicitly saying, ns-3 is a network Simulation/Simulator library version 3. (you decide which is technically correct to say at this point Simulation/Simulator of let it be both)

2) All the typical simulator core functionalities (including scheduler and other things -correct this) as well the basic & advanced networking related functionalities were implemented as shared library modules in ‘ns-3 library package(?)’.

3) To get a runnable instance of simulator, we have to write a simulation script (Test1.cc) using the both simulator core libraries and network related libraries along with our own custom simulation descriptions.

4) If we compile the simulation script (Test1.cc), then the final binary that contains simulator core, will schedule the events to run the descriptions that we organized in our simulation script (using the referenced network functionalities).

5. So the final binary that we got here will be our customized simulator (/Simulator Instance) called Test1 that will (only can)do things according to our simulation descriptions using the ns-3 library.

———————————–
6) We can add other contributed ns-3 libraries/models from ns-3 app store and other internet sources to extend the functionality of our simulations (Test1.cc).
For example, if we will need some advanced 5G related network functionalities, we may use contributed ns-3 libraries/models such as mmWave.

Explanation for point (3)

for example, if we write a (simulation) script “test.cc”

main() {

std::cout<<“testing 123”;

}

and compile it and run it as follows :

./waf –run test,

Then it will not be “Network Simulation” because, we are not having any networking functionalities here.
So, a simulation script can be called as a Network Simulation script, if and only if it is using the Simulator core libraries and some Networking related libraries in an organized manner. So, here, test.cc is definitely not a simulation script.

Note:
Mr. Tom, after continuously using ns-3 for more than a decade. Almost, the first 10 years I really do not know what it is -I just dropped it by saying ” சீ சீ இந்தப்பழம் புளிக்கும்” (TAMIL) -meaning “I don’t need any sour grapes“. So, I dropped ns-3 like that fox.

In fact, there were two reasons for this; the first and main reason is I could not find a simulator binary in it and the second reason was, ns-3’s immaturity at that time (at that time ns-3 did not have that many protocols implemented in it like ns-2)

What I said is truly my mental picture of ns-3 (after several years of effort towards understanding it correctly).
So, if you think that my convention will be useful for other to understand ns-3 in a better way, then you must even simply the above 6 point and give it as a brief introduction of ns-3. My request is you please try to correct the technical quality and most importantly try to reduce the number of words in those 6 lines.

After that 5 or 6 line, you may elaborately explain it with illustrations. It may save few years for someone like me in future to completely understand what is ns-3.

If you wish to share your views on this , I am waiting to hear it.

Charles Pandian,