Table of Contents
NS-3
License
- GNU GPL Version 2.0
Tricks and Traps
- Maintaining two officially supported installation methods: Bake (all-in-one) and Git (simpler)
- Sub-modules like ns.core and ns.network cannot be imported in the latest version of python bindings; the module structure has changed…?
- e.g., what used to be accessed as ns.flow_monitor.FlowMonitorHelper() is now available directly as ns.FlowMonitorHelper()
- Handling C++/Cppyy pointers is required; the following reference serves as a useful resource:
- Appropriate definitions should be added in ns.cppyy.cppdef if not supported in C++/Cppyy.
Installation via PyPI/Pip
https://www.nsnam.org/docs/manual/html/python.html
https://pypi.org/project/ns3/
pip install --user ns3 #pip install --user ns3==3.42.post2
Considerable differences in user experience can be observed between the version installed via pip and built from source with the 'Python Bindings' option.
The source-built version with Python Bindings provides greater flexibility and enables a wider range of functionality.
Troubleshooting - No Matching Distribution
## ERROR: Could not find a version that satisfies the requirement ns3 (from versions: none) ## ERROR: No matching distribution found for ns3
pip install --upgrade setuptools
Installation on Linux/Ubuntu (Version NS-3.42)
https://www.nsnam.org/docs/installation/singlehtml/
https://www.nsnam.org/docs/tutorial/html/getting-started.html
https://www.nsnam.org/docs/release/3.42/installation/html/
https://www.nsnam.org/docs/manual/html/python.html
https://www.nsnam.org/docs/manual/html/working-with-git.html
https://www.nsnam.org/docs/bake/tutorial/html/bake-tutorial.html
https://www.nsnam.org/wiki/Installation
Prerequisites
## Minimal Requirement #sudo apt install gcc sudo apt install g++ python3 cmake ninja-build git
## Recommended for Compiler Cache Optimization sudo apt install ccache
Information - Optional Components
## Python Visualizer and Bindings #python3 -m pip install --user cppyy #python3 -m pip install --user cppyy==2.4.2 python3 -m pip install --user cppyy==3.1.2 sudo apt install gir1.2-goocanvas-2.0 python3-gi python3-gi-cairo python3-pygraphviz gir1.2-gtk-3.0 ipython3
## Python Development sudo apt install python3-setuptools git
## Netanim Animator sudo apt install qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools sudo apt install qt5-default
## PyViz Visualizer sudo apt install gir1.2-goocanvas-2.0 python3-gi python3-gi-cairo python3-pygraphviz gir1.2-gtk-3.0 ipython3
## MPI-Based Distributed Emulation sudo apt install openmpi-bin openmpi-common openmpi-doc libopenmpi-dev
## Bake Build Tool sudo apt install mercurial unzip
## Debugging sudo apt install gdb valgrind
## Code Style Check sudo apt install clang-format
## Inline Documentation #sudo apt install doxygen graphviz imagemagick #sudo apt install texlive texlive-extra-utils texlive-latex-extra texlive-font-utils dvipng latexmk
## Manual and Tutorial #sudo apt install python3-sphinx dia
## GNU Scientific Library (GSL) for 802.11b WiFi Error Models sudo apt install gsl-bin libgsl-dev libgslcblas0
## PCAP Packet Traces sudo apt install tcpdump
## Statistics Framework sudo apt install sqlite sqlite3 libsqlite3-dev
## Config Store sudo apt install libxml2 libxml2-dev
## GTK-Based Configuration System sudo apt install libgtk-3-dev
## Experiment with Virtual Machines sudo apt install vtun lxc uml-utilities
## Openflow Module and Boost Development Libraries sudo apt install libxml2 libxml2-dev libboost-all-dev
Option A: Installation with Git (Our Recommendation)
https://www.nsnam.org/docs/manual/html/working-with-git.html
https://gitlab.com/nsnam/ns-3-dev
https://github.com/nsnam/ns-3-dev-git
git clone https://gitlab.com/nsnam/ns-3-dev.git cd ns-3-dev
#git checkout -b ns-3.46-release ns-3.46 git checkout -b ns-3.42-release ns-3.42
./ns3 clean
#./ns3 configure --enable-examples --enable-tests ./ns3 configure --enable-examples --enable-tests --enable-python-bindings
## -- ---- Summary of ns-3 settings: ## Build profile : default ## Build directory : /home/daiphys/ns-3-dev/build ## Build with runtime asserts : ON ## Build with runtime logging : ON ## Build version embedding : OFF (not requested) ## BRITE Integration : OFF (Missing headers: "Brite.h" and missing libraries: "brite") ## DES Metrics event collection : OFF (not requested) ## DPDK NetDevice : OFF (not requested) ## Emulation FdNetDevice : ON ## Examples : ON ## File descriptor NetDevice : ON ## GNU Scientific Library (GSL) : ON ## GtkConfigStore : ON ## LibXml2 support : ON ## MPI Support : OFF (not requested) ## ns-3 Click Integration : OFF (Missing headers: "simclick.h" and missing libraries: "nsclick click") ## ns-3 OpenFlow Integration : OFF (Missing headers: "openflow.h" and missing libraries: "openflow") ## Netmap emulation FdNetDevice : OFF (missing dependency) ## PyViz visualizer : ON ## Python Bindings : ON ## SQLite support : ON ## Eigen3 support : OFF (Eigen was not found) ## Tap Bridge : ON ## Tap FdNetDevice : ON ## Tests : ON ## ## Modules configured to be built: ## antenna aodv applications ## bridge buildings config-store ## core csma csma-layout ## dsdv dsr energy ## fd-net-device flow-monitor internet ## internet-apps lr-wpan lte ## mesh mobility netanim ## network nix-vector-routing olsr ## point-to-point point-to-point-layout propagation ## sixlowpan spectrum stats ## tap-bridge test topology-read ## traffic-control uan virtual-net-device ## visualizer wifi wimax ## ## Modules that cannot be built: ## brite click mpi ## openflow ## ## -- Configuring done ## -- Generating done ## -- Build files have been written to: /home/daiphys/ns-3-dev/cmake-cache
Make sure to check the status before building; the package build will fail or not proceed if the status shows 'OFF'.
./ns3 build
## [1943/1943] Linking CXX executable ../build/utils/ns3.42-test-runner-default ## Finished executing the following commands: ## /usr/bin/cmake --build /home/daiphys/ns-3-dev/cmake-cache -j 1
Troubleshooting - Wifi Test Warnings
## [1317/1943] Building CXX object src/wifi/CMakeFiles/libwifi-test.dir/test/wifi-mac-ofdma-test.cc.o ## ../src/wifi/test/wifi-mac-ofdma-test.cc: In member function ‘void OfdmaAckSequenceTest::CheckResults(ns3::Time, ns3::Time, uint8_t)’: ## ../src/wifi/test/wifi-mac-ofdma-test.cc:710:1: note: variable tracking size limit exceeded with ‘-fvar-tracking-assignments’, retrying without ## 710 | OfdmaAckSequenceTest::CheckResults(Time sifs, Time slotTime, uint8_t aifsn)
## [1329/1943] Building CXX object src/wifi/CMakeFiles/libwifi-test.dir/test/wifi-txop-test.cc.o ## ../src/wifi/test/wifi-txop-test.cc: In member function ‘void WifiTxopTest::CheckResults()’: ## ../src/wifi/test/wifi-txop-test.cc:462:1: note: variable tracking size limit exceeded with ‘-fvar-tracking-assignments’, retrying without ## 462 | WifiTxopTest::CheckResults()
To be investigated; just ignoring these failures for the moment.
Option B: Installation with Bake
https://www.nsnam.org/docs/bake/tutorial/html/bake-tutorial.html
mkdir ns-3 cd ns-3
git clone https://gitlab.com/nsnam/bake
export BAKE_HOME=`pwd`/bake export PATH=$PATH:$BAKE_HOME export PYTHONPATH=$PYTHONPATH:$BAKE_HOME
bake.py check #bake.py configure -e ns-3.42 bake.py configure -e ns-allinone-3.42 bake.py show
## -- System Dependencies -- ## > automake - OK ## > cmake - OK ## > cppyy - OK ## > g++ - OK ## > gi-cairo - OK ## > gir-bindings - OK ## > libxml2-dev - OK ## > mercurial - OK ## > pygobject - OK ## > pygraphviz - OK ## > python3-dev - OK ## > qt - OK
bake.py deploy #bake.py download #bake.py build
## Downloading, building and installing the selected modules and dependencies. ## Please, be patient, this may take a while! ## >> Searching for system dependency libxml2-dev - OK ## >> Downloading click-ns-3.37 - OK ## >> Searching for system dependency g++ - OK ## >> Searching for system dependency cppyy - OK ## >> Searching for system dependency gi-cairo - OK ## >> Searching for system dependency gir-bindings - OK ## >> Searching for system dependency pygobject - OK ## >> Searching for system dependency pygraphviz - OK ## >> Searching for system dependency python3-dev - OK ## >> Searching for system dependency qt - OK ## >> Searching for system dependency cmake - OK ## >> Searching for system dependency mercurial - OK ## >> Searching for system dependency automake - OK ## >> Downloading openflow-dev - OK ## >> Downloading netanim-3.109 - OK ## >> Downloading BRITE - OK ## >> Downloading ns-3.42 (target directory:ns-3.42) - OK ## >> Building click-ns-3.37 - OK ## >> Building openflow-dev - OK ## >> Building netanim-3.109 - OK ## >> Building BRITE - OK ## >> Building ns-3.42 - OK
cd source/ns-3.42
./ns3 show
## Build profile: default ## ns-3 version: ns-3.42 ## Reconfigure with './ns3 configure --enable-build-version' to bake the version into the libraries. ## ---- Summary of ns-3 settings: ## Build profile : default ## Build directory : /home/daiphys/source/ns-3.42/build ## Build with runtime asserts : ON ## Build with runtime logging : ON ## Build version embedding : OFF (not requested) ## BRITE Integration : ON ## DES Metrics event collection : OFF (not requested) ## DPDK NetDevice : OFF (not requested) ## Emulation FdNetDevice : ON ## Examples : ON ## File descriptor NetDevice : ON ## GNU Scientific Library (GSL) : ON ## GtkConfigStore : ON ## LibXml2 support : ON ## MPI Support : OFF (not requested) ## ns-3 Click Integration : ON ## ns-3 OpenFlow Integration : ON ## Netmap emulation FdNetDevice : OFF (missing dependency) ## PyViz visualizer : OFF (missing Python Bindings) ## Python Bindings : OFF (missing dependency: cppyy) ## SQLite support : ON ## Eigen3 support : OFF (Eigen was not found) ## Tap Bridge : ON ## Tap FdNetDevice : ON ## Tests : ON ## ## Modules configured to be built: ## antenna aodv applications ## bridge brite buildings ## click config-store core ## csma csma-layout dsdv ## dsr energy fd-net-device ## flow-monitor internet internet-apps ## lr-wpan lte mesh ## mobility netanim network ## nix-vector-routing olsr openflow ## point-to-point point-to-point-layout propagation ## sixlowpan spectrum stats ## tap-bridge test topology-read ## traffic-control uan virtual-net-device ## wifi wimax ## ## Modules that cannot be built: ## mpi visualizer ## ## ---- Summary of buildable targets: ## Buildable targets: 80 ## Runnable/Buildable targets: 294
#./ns3 configure --enable-examples --enable-tests ./ns3 configure --enable-examples --enable-tests --enable-python-bindings
Make sure to check the status before building; the package build will fail or not proceed if the status shows 'OFF'.
./ns3 build
Troubleshooting - Cppyy Missing Dependency
## -- Bindings: python bindings disabled due to the following missing dependencies: cppyy ## Python Bindings : OFF (missing dependency: cppyy)
python3 -m pip uninstall cppyy cppyy-backend cppyy-cling CPyCppyy python3 -m pip install --verbose cppyy==3.1.2
Using Pip or Git would be alternatives.
Troubleshooting - Bindings Install Directory
## -- NS3_BINDINGS_INSTALL_DIR was not set. The python bindings won't be installed with ./ns3 install. This setting is meant for packaging and redistribution. ## -- Set NS3_BINDINGS_INSTALL_DIR="/home/user/.local/lib/python3.8/site-packages" to install it to the default location.
To be investigated; just ignoring this warning for the moment.
Testing
./test.py
## [ 0%] Building CXX object src/antenna/CMakeFiles/libantenna-obj.dir/model/circular-aperture-antenna-model.cc.o ## [ 0%] Building CXX object src/antenna/CMakeFiles/libantenna-obj.dir/model/angles.cc.o ## [ 0%] Building CXX object src/antenna/CMakeFiles/libantenna-obj.dir/model/antenna-model.cc.o ## [ 0%] Building CXX object src/antenna/CMakeFiles/libantenna-obj.dir/model/cosine-antenna-model.cc.o ## [ 0%] Building CXX object src/antenna/CMakeFiles/libantenna-obj.dir/model/isotropic-antenna-model.cc.o ## ... ## [773/780] PASS: Example src/buildings/examples/buildings-pathloss-profiler ## [774/780] PASS: Example src/buildings/examples/outdoor-group-mobility-example --useHelper=0 ## [775/780] PASS: Example src/buildings/examples/outdoor-group-mobility-example --useHelper=1 ## [776/780] PASS: Example src/brite/examples/brite-generic-example ## [777/780] PASS: Example src/bridge/examples/csma-bridge ## [778/780] PASS: Example src/bridge/examples/csma-bridge-one-hop ## [779/780] PASS: Example src/aodv/examples/aodv ## 780 of 780 tests passed (780 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)
Path Settings (if Python Bindings)
export NS3PATH=/home/daiphys/ns-3-dev
export PATH=${PATH}:${NS3PATH}/build/bindings/python
export PATH=${PATH}:${NS3PATH}/build/lib
export PYTHONPATH=${PYTHONPATH}:${NS3PATH}/build/bindings/python
export PYTHONPATH=${PYTHONPATH}:${NS3PATH}/build/lib
Tutorials (C++)
Hello Simulator
./ns3 run hello-simulator
## [ 0%] Building CXX object examples/tutorial/CMakeFiles/hello-simulator.dir/hello-simulator.cc.o ## [ 0%] Linking CXX executable ../../../build/examples/tutorial/ns3.42-hello-simulator-default
## Hello Simulator
First: Point to Point
## Default Network Topology ## 10.1.1.0 ## n0 -------------- n1 ## point-to-point
./ns3 run first
## [ 0%] Building CXX object examples/tutorial/CMakeFiles/first.dir/first.cc.o ## [ 0%] Linking CXX executable ../../../build/examples/tutorial/ns3.42-first-default
## At time +2s client sent 1024 bytes to 10.1.1.2 port 9 ## At time +2.00369s server received 1024 bytes from 10.1.1.1 port 49153 ## At time +2.00369s server sent 1024 bytes to 10.1.1.1 port 49153 ## At time +2.00737s client received 1024 bytes from 10.1.1.2 port 9
../netanim-3.109/NetAnim ## Open animation.xml on NetAnim
Troubleshooting - No Visualizer
https://www.nsnam.org/wiki/PyViz
./ns3 run --vis first
## NS_ASSERT failed, cond="uid != 0", msg="Assert in TypeId::LookupByName: ns3::VisualSimulatorImpl not found", file=source/ns-3.42/src/core/model/type-id.cc, line=840 ## NS_FATAL, terminating ## terminate called without an active exception ## Command 'build/examples/tutorial/ns3.42-first-default --SimulatorImplementationType=ns3::VisualSimulatorImpl' died with <Signals.SIGABRT: 6>.
## Check if Python Bindings and PyViz Visualizer are ON ./ns3 show
Star Animation
./ns3 run star-animation
../netanim-3.109/NetAnim ## Open star-animation.xml on NetAnim
Dumbbell Animation
./ns3 run dumbbell-animation
../netanim-3.109/NetAnim ## Open dumbbell-animation.xml on NetAnim
Tutorials (Python)
First: Point to Point
python3 ./examples/tutorial/first.py
## At time +2s client sent 1024 bytes to 10.1.1.2 port 9 ## At time +2.00369s server received 1024 bytes from 10.1.1.1 port 49153 ## At time +2.00369s server sent 1024 bytes to 10.1.1.1 port 49153 ## At time +2.00737s client received 1024 bytes from 10.1.1.2 port 9
Troubleshooting - No Mobility Model
## [runStaticInitializersOnce]: Failed to materialize symbols: { (main, { $.cling-module-141.__inits.0, __orc_init_func.cling-module-141, _GLOBAL__sub_I_cling_module_141, _ZN3ns3L16g_timeInitHelperE, __cxx_global_var_initcling_module_141_ }) }
## [runStaticInitializersOnce]: Failed to materialize symbols: { (main, { __orc_init_func.cling-module-141 }) }
To be investigated; just ignoring these failures for the moment.
Troubleshooting - No Mobility Model
## AnimationInterface WARNING:Node:0 Does not have a mobility model. Use SetConstantPosition if it is stationary ## AnimationInterface WARNING:Node:1 Does not have a mobility model. Use SetConstantPosition if it is stationary
mobility = ns.MobilityHelper()
mobility.SetMobilityModel("ns3::ConstantPositionMobilityModel")
mobility.Install(nodes)
UDP Relay
Simple Version
Source and Results:
ns3_relay_udp_simple.tar.gz
Source and Results (with Tracer):
ns3_relay_udp_simple_trace.tar.gz
## === Simulation Results === ## Execution Time : 5.011059 s ## Transmitted Packets : 6 packet(s) ## Received Packets : 6 packet(s) ## Packet Loss : 0 packet(s) ## Packet Loss Rate : 0.000000 ## Received Data : 6324 bytes ## Received Payload : 6156 bytes ## Throughput (pps) : 1.197352 packets/s ## Throughput (bps) : 9827.862341 bits/s ## Throughput (Bps) : 1228.482793 bytes/s ## Latency Min : 11.059200 ms ## Latency Max : 11.059200 ms ## Latency Mean : 11.059200 ms ## Jitter (PDV Mean) : 0.000000 ms ## Jitter (RFC3550) : 0.000000 ms
Custom Version
Source and Results:
ns3_relay_udp_custom.tar.gz
## === Simulation Results === ## Execution Time : 6.144131 s ## Transmitted Packets : 14000 packet(s) ## Received Packets : 13285 packet(s) ## Packet Loss : 715 packet(s) ## Packet Loss Rate : 0.051071 ## Received Data : 3772940.0 bytes ## Received Payload : 3400960.0 bytes ## Throughput (pps) : 2162.225963 packets/s ## Throughput (bps) : 4428238.771985 bits/s ## Throughput (Bps) : 553529.846498 bytes/s ## Latency Min : 25.372800 ms ## Latency Max : 204.624914 ms ## Latency Mean : 148.464855 ms ## Jitter (PDV Mean) : 0.051982 ms ## Jitter (RFC3550) : 0.057935 ms
TCP Relay
Simple Version
Source and Results:
ns3_relay_tcp_simple.tar.gz
Source and Results (with Tracer):
ns3_relay_tcp_simple_trace.tar.gz
## === Simulation Results === ## Execution Time : 6.225210 s ## Transmitted Packets : 2084 packet(s) ## Received Packets : 2084 packet(s) ## Packet Loss : 0 packet(s) ## Packet Loss Rate : 0.000000 ## Received Data : 2243484 bytes ## Received Payload : 2160124 bytes ## Throughput (pps) : 334.767834 packets/s ## Throughput (bps) : 2775969.413468 bits/s ## Throughput (Bps) : 346996.176684 bytes/s ## Latency Min : 6.259200 ms ## Latency Max : 183.654400 ms ## Latency Mean : 109.321236 ms ## Jitter (PDV Mean) : 3.828856 ms ## Jitter (RFC3550) : 8.596200 ms ## RTT Min : 12.000000 ms ## RTT Max : 217.904953 ms ## RTT Mean : 111.515605 ms
General Version
Source and Results (with Tracer):
ns3_relay_tcp_general_trace.tar.gz
## === Simulation Results === ## Execution Time : 6.414094 s ## Transmitted Packets : 5702 packet(s) ## Received Packets : 5702 packet(s) ## Packet Loss : 0 packet(s) ## Packet Loss Rate : 0.000000 ## Received Data : 6140620 bytes ## Received Payload : 5912540 bytes ## Throughput (pps) : 888.979744 packets/s ## Throughput (bps) : 7374434.651289 bits/s ## Throughput (Bps) : 921804.331411 bytes/s ## Latency Min : 6.129600 ms ## Latency Max : 162.038400 ms ## Latency Mean : 67.553666 ms ## Jitter (PDV Mean) : 4.752526 ms ## Jitter (RFC3550) : 0.962728 ms ## RTT Min : 12.000000 ms ## RTT Max : 152.794548 ms ## RTT Mean : 81.599223 ms
Route Switching
Custom Version
Source and Results:
ns3_relay_tcp_custom.tar.gz
## === Simulation Results === ## Execution Time : 6.064738 s ## Transmitted Packets : 8000 packet(s) ## Received Packets : 8000 packet(s) ## Packet Loss : 0 packet(s) ## Packet Loss Rate : 0.000000 ## Received Data : 2368000 bytes ## Received Payload : 2048000 bytes ## Throughput (pps) : 1319.100677 packets/s ## Throughput (bps) : 2701518.185501 bits/s ## Throughput (Bps) : 337689.773188 bytes/s ## Latency Min : 25.488001 ms ## Latency Max : 228.113200 ms ## Latency Mean : 59.244269 ms ## Jitter (PDV Mean) : 0.060806 ms ## Jitter (RFC3550) : 0.000000 ms
References
Network Simulator (NS-3)
https://www.nsnam.org/
https://www.nsnam.org/docs/release/3.45/doxygen/
https://www.nsnam.org/docs/release/3.45/doxygen/db/d70/_groups_list.html
Official Git
https://gitlab.com/nsnam/ns-3-dev
https://github.com/nsnam/ns-3-dev-git
Official PyPI
https://pypi.org/project/ns3/
Users Mailing List
https://groups.google.com/g/ns-3-users
https://github.com/Gabrielcarvfer/ns3_for_education
https://qiita.com/dorapon2000/items/72dcc08eb3c8857f5603
https://qiita.com/dorapon2000/items/5c0c0a399aeee629be63
https://qiita.com/bmt/items/b16d90730e9e398774f8
https://qiita.com/haltaro/items/b474d924f63692c155c8
https://qiita.com/RIckyBan/items/37ae69e991c125c5eb5f
https://qiita.com/haltaro/items/d479538345357f08c595