Confusions in Contributing Our New Model to ns-3

[Charles Pandian]

For a very long time, I wish to contribute my own little things to ns-3. But whenever I read the guide on contributing to ns-3, I could not able to understand that procedure at some point, and it discouraged me to proceed. So there should be some "idot's guide on contributing to ns-3" - so that, it will be easy for people like me to contribute something to ns-3.

The reason for posting this here is to get feedback from developers and experts so that one can understand the ways of the submission process and can easily contribute his/her code/model to ns-3 and make it available for all along with the official ns-3 distribution. I am writing an article on "Confusions in Contributing Our New Model to mainline ns-3." to share my experience of "trying to contribute to ns-3".

To make one to understand the problems that I faced while trying to learn the standards in contributing a new module or patch to ns-3, I hereby explain it with my examples scenario.

I  want to contribute two new mobility models for ns-3 namely, 

• CircleMobilityModel and
• SpringMobilityModel

In  fact, I already explained the way in which I developed them in the following two posts :

• Implementation of Circle Mobility Model for ns-3 and Visualizing it in 3D
• Implementation of Spring Mobility Model for ns-3 and Visualizing it in 3D along with Circle Mobility

So that, anyone can learn the way of implementing a simple mobility model by following the above procedure.In fact, I developed these two mobility models with little effort. But making a submission to incorporate it with mainline ns-3 seems to be a nightmare to me.

But I want my Mobility Models to be merged with the mainstream ns-3 code so that anyone can use it with the default installation of ns-3.

The General section of the official ns-3 contribution guide explains the following

• Licensing our code
• Editing Copyright Section of the code
• Giving Attribution to Others
• Coding style
• Creating a patch
• Becoming a Maintainers

First Doubt

Let me start with my first doubt -  Naming my New Mobility models:

I am having a 'silly wish' to name the mobility models with my name like :

"CharlesCircleMobilityModel"

"CharlesSpringMobilityModel"

Will this kind of naming discourage the developers to allow this model during the review?

Another concern regarding naming is:

ndnSIM already has a mobility model called "SpringMobilityModel" for ns-3

Someone also already implemented "CircelMobilityModel" for ns-3 (sorry I could not find the link now)

So, in addition, to making me happy :-) , this way of naming will avoid confusion with some other similar implementations with the same name.

Second Doubt

I started to develop these two new mobility models by cloning the skeleton structure of "ConstantPositionMobilityModel" by Mathieu Lacage.

Only a few standard declaration lines are directly handled from ConstantPositionMobilityModel code, and most 90% of lines on my new models were only rewritten by me. But, I wish to give credit to Mathieu Lacage for making me understand the simplicity of a mobility model with his code.

Will the following lines in the header section of my new model code satisfy the (1)Licensing, (2)Copyright and the (3) Attribution standards?

 

/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
* Copyright (c) 2021 Charles Pandian, ProjectGuideline.com
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 2 as
* published by the Free Software Foundation;
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* Author: Charles Pandian<igs...@gmail.com>
* Insprired from: ConstantPositionMobilityModel by Mathieu Lacage <mathieu...@sophia.inria.fr>
*/

Third Doubt

This is the main doubt that is discouraging me to contribute something to ns-3.

 

In fact, I could not understand what a new model to satisfy the need of the automated testing described in the section "How to write tests".

Frankly saying I can not understand what they are taking in this section (simply it is in alien language)

Is there any simple document that will explain about this testing?
Or is there any simple example of 'testing' that is needed for a simple 'hello' ns-3 model?

I followed the procedure and run the script create-module.py for creating the directory structure for my new model "CharlesCircleMobilityModel".  It is creating folders with some example/dummy(?) files under the contrib folder.

1. 1. Of course, I can give some documentation under "doc" folder by editing the provided file (or will it autogenerate documentation by running Doxygen on my model code?)
   2. Even I will provide some examples under the "examples" folder.
   3. My simple mobility models do not need any helper functions. (should I delete this?is it allowed to submit a model without 'helper' code?)
   4. Even I can keep my model code under the "model" folder.
   5. Frankly saying, I am not having any idea for doing anything under 'test' folder. (may I delete this? is it allowed to submit a model without 'test' code?)

 

But, I simply want my new mobility models to live under the folder "ns-allinone-3.35/ns-3.35/src/mobility/model" of the ns-3 distribution.

But the documentation is advising me to do it using 'create-module.py' with several folders.

If I submit the code with the above structure, will the developers of ns-3 merge it under "ns-allinone-3.35/ns-3.35/src/mobility/model" ? (and examples under "ns-allinone-3.35/ns-3.35/src/mobility/examples", .... )

 

Kindly someone explain what I need to do for making my model live at "ns-allinone-3.35/ns-3.35/src/mobility/model" in future versions of ns-3 distributions.

Of course, it will not make much confusion if I develop a 'big routing algorithm like' model that will  live under ns-allinone-3.35/ns-3.35/src/

For submitting a simple add-on module like a mobility model, what are the conventions one should fulfil before submitting it for review?

Somebody, please Explain.

 

Mode  of Submissions

The guide on contributing to ns-3 tries to explain the following way of submitting a new model/patch to ns-3.

• Submitting as a patch
• Submitting as enhancement
• Submitting as externally maintained code
• Submitting as a new model

   

Even though I can not fully understand the exact procedures of the above four methods, I can understand that all the above methods will lead to incorporating our new ns-3 model in a future version of ns-3 after some review and a lot of time.

But the last submission method is like Directly Uploading files at GitLab, and it will get merged with the official release after some  review (and of course it will satisfy  all the standards outlined in the  contribution  guide)

Fourth  Doubt

Submitting as a Merge Request or Upstreaming to ns-3-dev by Directly Uploading files at GitLab will be a suitable way to submit a simple model like the mobility models that I mentioned here?

I mean, is it allowed to directly upload my

            mobility model files (.cc and .h) under https://gitlab.com/nsnam/ns-3-dev/-/tree/master/src/mobility/model and

            the corresponding examples under https://gitlab.com/nsnam/ns-3-dev/-/tree/master/src/mobility/examples ?

Will it get reviewed and accepted to mainline ns-3 if it satisfies the conditions? (I mean without "test" and a separate "doc")

I mean, what are the basic things that a model code should fulfil - so that it will be accepted?

The Last(?) Doubt

While trying to learn the way of contributing to ns-3, here and there, I saw some python based scripts and ways of doing things. Since as per the recent announcement, the python bindings will be removed from ns-3 and there will be a 'make' way of compiling things.

Will these new changes affect the ways of making/submitting the contribution? the official contribution guide is not discussing future issues related to this python and 'make' changes.

Note: 

Of course, the official documents provide LOT of information regarding the submission. But its hugeness itself makes it impossible for us to contribute a 'simple' thing to the official version of ns-3.

I hope that the developers and experts can understand my concerns and will provide some insights in this regard.  Your simple replies not only help me to make my first contribution to ns-3.  It will help a student/scholar to really contribute something to ns-3.

Charles Pandian,

[shattered...@gmail.com]

Dear Charles,

I saw your post a couple of days ago, but I haven't seen any reply. So I decide to give you my opinion on the matter.

By no means I am an expert in the matter, but I have contributed some code to the ns-3 main repository.

First Doubt Answer:

Regarding naming the Model with your own name, I would say it's discouraged.  This is not written in stone by any means, but it is often encouraged to use naming conventions that

explain the purpose of the model without needing to check what the model does. Unless your model is so revolutionary or so unique, I would say stick to simple names.

I understand the need for recognizing your hard work creating the module, but your name is already at the top of the code and added to the list of contributors, do you really need more?

Also, if other similar modules already exist, you might be asked to complement or add to those modules instead. Typically, only modules that can serve a wide audience are added to the main repository.

Again... not a rule, just something that I have seen.

Second Doubt Answer:

Most of the code you see in ns-3 is based on other contributors. So is not unusual to base your work on other modules. If the module is "too similar" then it is possible it might be rejected. 

This is determined by the evaluator of the module when your code is reviewed.  I would say is ok to put your name as author and mentioned that your code is based on the code of Mathieu.

Not no need to add his e-mail since he would not answer questions about your code.

Third Doubt Answer:

There are like 5 questions in here. But... I'll do my best.

- For a new mobility model, your code should be added to the general folder of  mobility/model. along the other mobility models.

Do not make new folders. Add your test or examples to the mobility/test and mobility/examples as required.

- I agree, The test-creating explanation can use some improvement by making it a more down-to-earth explanation. Ns-3 main contributors make a yearly survey about how to improve the help and descriptions in the site.

 you can bring your concern there.  In the meantime, there's not much else to do but to give it a try. See the examples of other tests to understand the logic behind these tests.

-Some code might not require tests, sometimes just an example is enough. However, is often encouraged to do tests. Depending on the module type.

Tests in ns-3 are meant to be a sort of protection against others modifying the code of ns-3 in a way that would affect the performance of your module.

In a test, your code should always behave in a certain way under some conditions (determined by the programmer), if it doesn't an "alarm" is issued. This tells the contributors that a recent change in some other ns-3 module

impacted your module.

For example, you could do a test for sending and receiving packets. Under some specified conditions, the packets should always be received in a specific time when the test was created.

If at some point somebody messes with the PHY or MAC layer and this changes the time of the reception in your test, an alarm would be issued for that test. The contributor then will proceed to check whether or not the new changes

are valid and maybe update your test or re-check the recent modifications.

-Submissions nowadays are done using merge requests in gitlab. There's a guide to do your contribution, look for it on the site.

https://gitlab.com/nsnam/ns-3-dev

Fourth Doubt Answer:

Again there's a guide for submissions. The minimum requirement is described in the guide.

But to summarize these requirements:

Your code needs at least have one example. 

You also need to add the documentation, but the doxygen documentation is the very least you need (see below).

In some cases, you might require a test but it is not always mandatory in my experience.

The code must have the correct copyright and follow the GNU coding style. Coding style  (variables naming, spacing capital letters, etc , etc) is very important.

There is a script in ns-3 to help you with that. 

You also need to add comments for the auto-generation of the doxygen documentation. Again, it's all there in the guide (https://www.nsnam.org/docs/contributing/html/index.html).

After you do your merge request.... the review might take a while depending on the reviewer. The response time is far from good but considering that this is all done by volunteers so you cant compain.

if you are patient you should get a response.

Last Doubt Answer:

I am not completely sure. I haven't heard anything about removing support for Python.

Python bindings are an option during the installation of ns-3. Of course, if you do not install the bindings you cannot use any python code in ns-3.

But that does not mean you cannot contribute in python. Mind you, your code might not be usable by those who opt not to use python bindings (like myself).

Some other main ns-3 developers can give you a better response on this than me.

I hope this solves some of your concerns about ns-3 contribution process.

Happy coding.

Regards,

Alberto Gallegos

[Charles Pandian]

Dear Alberto Gallegos,

Thank you for your advice. Certainly, some of your suggestions will help me to refine my SR 821 on ns-3-dev which is already under discussion.

If possible, please share your insights at the unresolved thread of SR 821 

Thank you for providing reply at the group.  Not only me, others also get benefit from your reply at the group.

Charles Pandian,

--
You received this message because you are subscribed to the Google Groups "ns-3-reviews" group.
To unsubscribe from this group and stop receiving emails from it, send an email to ns-3-reviews...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/ns-3-reviews/b1393ba1-8038-4025-af62-c7907d65c700n%40googlegroups.com.