Topic: ns-3 examples
- Sept 15, 2022 08:00 AM Pacific Time (US and Canada), 15h00 UTC
The session was led by Mohit Tahiliani.
This session focuses on the usability aspects of ns-3, especially the examples. The ns-3 repository has a large number of examples. Most of the examples are available in the ‘examples/’ directory but quite a few are also available in ‘src//examples’ directories. Typically, a new example is added to the repository when a new feature is introduced in ns-3. However, in the majority of the cases, the new examples being added are not (and sometimes, they cannot be) an incremental update of existing examples. This could be due to the fact that existing examples are not suitable to be updated to demonstrate the new feature being added or maybe the developers find it more convenient to work on the examples that they have already developed for their work. This has led to the ns-3 repository having a large number of examples, but with little to no continuity. Currently, it is not possible to draw a lineage, or a set of small lineages, among the examples that are available in ns-3. Consequently, this makes it difficult for the ns-3 users to incrementally learn the features supported by ns-3. In this session, we will discuss the possible ways to restructure the examples in the ns-3 repository to make it easy for ns-3 users to get started, and comfortably move further with simulating advanced features using ns-3.
The session was attended by Mohit Tahiliani, Tom Henderson, Biljana Bojovic, Eduardo Almeida, and Tommaso Pecorella.
ns-3 has roughly 300 example programs, distributed in the examples directory and also the examples directories in each module. They have inconsistent style and the location of relevant examples differs from module to module. It can be very hard for a newcomer to figure out what are the useful examples and where they are located. There is also a lack of continuity in the tutorial presentation-- it does not incrementally build on a single topology. Finally, documentation on examples is sparse. We also haven't taken the opportunity to improve the helpers based on experience with configuring examples.
Mohit plans to work on a revamp of examples with several of his students. This is motivated by his similar work in preparing examples for the NeST tool. He envisions a 'getting-started' directory which helps users incrementally set up topology, nodes, links, bandwidth (including asymmetric) and delay. From here, the next proposed directory is a tracing directory which provides examples on ascii and pcap traces, flow monitor, trace sources, and gnuplot. From there, users can move to technology-specific examples such as wifi, lte, tcp, lr-wpan, etc. with this common base. Each technology area should also have its 'getting-started' example. This will provide multiple entry points. We can connect more advanced examples to these, and possibly improve helpers.
Tommaso cautioned about an explosion of files very similar to one another. Instead, look into modularity. Also, some kind of inversion of control pattern (setup, run, teardown) might help in this regard, rather than making all examples linear main() functions. Biljana followed on by saying that they had similar difficult issues with code reuse in advanced LTE examples.
Tom commented that we could solve some issues by naming some files as 'recipes', some as 'examples' and some as 'experiments'. Would like well-worked examples for several topics such as TCP congestion control, Wi-Fi rate control, etc. Also, a documentation page (markdown) associated with each example would help, listing the objectives of the example, what output it produces, what options are provided and why, etc. Tommaso suggested perhaps making the per-module examples into recipes only.