ns-3 & MATLAB Docker images

ns-3 and MATLAB Runtime bundles using Docker.

The scope of this repository is to automate the installation process of both ns-3 and MATLAB Runtime, in order to provide a hassle-free setup process for a simulation environment.

Images are based on either egiona/ns3-base or egiona/ns3-woss, shipping with MATLAB Runtime. Please refer to ns3-base or ns3-woss repositories for further details regarding available ns-3 and/or WOSS configurations and utilities.

Available configurations (latest first)

Docker image name: egiona/ns3-matlab.

Based on egiona/ns3-base | Docker image tag | egiona/ns3-base | MATLAB Runtime | Dockerfile | | :---: | :---: | :---: | :---: | | base-n3.40-m2023b | u22.04-n3.40 | 2023b (Update 6) | link | | base-n3.40-m2023a | u22.04-n3.40 | 2023a (Update 6) | link | | base-n3.40-m2022b | u22.04-n3.40 | 2022b (Update 8) | link |

Based on egiona/ns3-woss | Docker image tag | egiona/ns3-woss | MATLAB Runtime | Dockerfile | | :---: | :---: | :---: | :---: | | woss-n3.40-m2023b | u22.04-n3.40-w1.12.6 | 2023b (Update 6) | link | | woss-n3.40-m2023a | u22.04-n3.40-w1.12.6 | 2023a (Update 6) | link | | woss-n3.40-m2022b | u22.04-n3.40-w1.12.6 | 2022b (Update 8) | link |

Full changelog can be found at this page.

Contributing

Any problems should be reported via the GitHub issue tracker.

Users are welcomed to contribute new images (e.g. different base image or other ns-3 versions) via Pull Request and adhering to the following style:

• Directory named <A-B-C> with: A equal to an arbitrary versioned base image short-hand (i.e. base refers to ns3-base, whereas woss refers to ns3-woss used as starting image); B equal to the ns-3 version bundled (i.e. n3.40 refers to ns-3.40); and C equal to the MATLAB Runtime version bundled (i.e. m2022b refers to MATLAB Runtime for MATLAB 2022b).

  Such directory name will also be used as image tag.

• The directory shall contain a well-commented Dockerfile for the image creation.

  Other contents may be freely modified.

Usage guidelines

Core instructions

The following instructions should apply to all platforms supported by Docker. However, utility scripts are only provided for UNIX-like systems.

1. Install Docker (please refer to official guidelines w.r.t. your own OS)

2. Select your desired Docker image according to the table above using

   docker pull egiona/ns3-matlab:<tag>

3. Retrieve the desired image identifier using

   docker images

4. Launch a container using the selected image using

   docker run -td --name <container name> <image ID>

5. Launch a live terminal from the container using

   docker exec -it <container ID or name> /bin/bash

   You can obtain a running container's ID using  docker ps , or  docker container ls -a (the latter also includes containers in any state).

6. Be aware that, prior to its usage with hereby Docker images, all MATLAB code must be compiled under a licensed MATLAB environment comprehensive of MATLAB Compiler.

   N.B. Please ensure that the desired Docker image is bundled with a MATLAB Runtime version equal to that of your MATLAB installation.
   For instance: ns3-matlab:base-n3.40-m2023b supports executables created by MATLAB w/ Compiler version 2023b only, regardless of Update number (more details here).

   Please refer to MATLAB Compiler instructions for compiling your MATLAB source code into Linux-compatible executables.

Utility scripts

1. You can switch between debug and optimized builds of ns-3 (see details) using

   ./build-debug.sh or ./build-optimized.sh respectively

   The aforementioned utility scripts are placed in the directory /home of a container's filesystem for both base images ns3-base and ns3-woss.

2. A utility script in the form of a Makefile is provided.

   Similarly to build scripts, this utility Makefile is placed in the directory /home of a container's filesystem.

   This script allows for easy decoupling of development directory from ns-3's source directory. Indeed, it is possible to keep novel modules and program driver scripts outside src (or contrib) and scratch directories of the ns-3 installation directory during development, and only copying them afterwards. This is especially useful when paired with mounted directories.

   Multiple targets are present, allowing: ns-3 current version checking, compilation and execution of simulation driver programs (copying them to scratch subdir first), management of ns-3 modules (creation in contrib subdir and copy outside, synchronization of contents, elimination), and debugging (GNU debugger, Valgrind, ns-3 tests).

   Use the following command for all details:

   make help

Optional instructions

As long as you docker restart the same container, any modification to its contents will be preserved. However, it is advisable to keep a local backup copy of your modules and experiment results.

1. Copy an arbitrary local file into the container's filesystem using

   docker cp <path/to/file> <container ID>:<desired/path/to/file>

2. Copy an arbitrary container's file to local filesystem using

   docker cp <container ID>:<path/to/file> <local/path/to/file>

3. Mount a local directory into a container (just once, instead of docker run) using

   docker run -td --mount type=bind,source=<local/FS/path>,target=<container/FS/path> --name <container name> <image ID>

   Paths to be mounted must be absolute.

   This is only needed the first time a container is instantiated, subsequent calls to  docker start on the same container will automatically load the mounted directory.

4. An environment variable CXX_CONFIG is available for user-defined scripts to adapt their GCC compilation parameters; by default, such variable holds the following contents:

   CXX_CONFIG="-Wall -Werror -Wno-unused-variable"

   Moreover, build scripts have been updated to provide an exit value reflective of ns-3's configuration and build outcome.

Citing this work

If you use any of the Docker images described in this repository, please cite this work using any of the following methods:

APA Giona, E. ns-3 and MATLAB Runtime Docker images [Computer software]. https://doi.org/10.5281/zenodo.10671738

BibTeX @software{Giona_ns-3_and_MATLAB, author = {Giona, Emanuele}, doi = {10.5281/zenodo.10671738}, license = {MIT}, title = {{ns-3 and MATLAB Runtime Docker images}}, url = {https://github.com/emanuelegiona/ns3-matlab-docker} }

Bibliography entries generated using Citation File Format described in the CITATION.cff file.

License

Copyright (c) 2024 Emanuele Giona (SENSES Lab, Sapienza University of Rome)

This repository and Docker images themselves are distributed under MIT license.

However, ns-3, WOSS, and MATLAB Runtime are distributed under their respective licenses: ns-3 license, WOSS license, MATLAB Runtime license (2022b). All installed packages may also be subject to their own license, and the license chosen for the Docker images does not necessarily apply to them.

Diclaimer: Docker, Ubuntu, ns-3, WOSS, MATLAB, MATLAB Runtime and other cited or included software belongs to their respective owners. Moreover, this shall NOT be considered an official MathWorks product.