Komondor: An IEEE 802.11ax Simulator

Agent-related content available here.

Table of Contents

Authors

Both authors have the same contribution to this project.

Introduction

Komondor is a wireless network simulator that includes novel mechanisms for next-generation WLANs, such as dynamic channel bonding or enhanced spatial reuse. One of the main purposes of Komondor is to simulate the behavior of IEEE 802.11ax-2019 networks, an amendment designed to boost spectral efficiency in dense deployments.

Komondor has been conceived as an open source tool that contributes to the ongoing research in wireless networks, especially regarding the implementation of novel functionalities that are not available in other well-known wireless simulators. In addition, it has been prepared for a simple integration with Machine Learning (ML) modules.

The project is structured as follows:

Doxygen documentation available here.

Overview

The code to run simulations is organized as follows:

An overview of the current modules available in Komondor is next shown:

Usage

Detailed installation and execution instructions can be found in the Komondor User's Guide.

In short, to run Komondor, just build the project by using the "build_local" script and then execute it by following the next steps:

STEP 0: Set permissions to the folder

$ chmod -R 777 <dirname>

STEP 1: Build the project

$ ./build_local

STEP 2: Run Komondor simulator for the given input information (basic simulation)

$ ./komondor_main INPUT_FILE_NODES OUTPUT_FILE_LOGS FLAG_SAVE_NODE_LOGS FLAG_PRINT_SYSTEM_LOGS FLAG_PRINT_NODE_LOGS SIM_TIME SEED

The inputs are further described next:

IMPORTANT NOTE (!): Setting FLAG_SAVE_NODE_LOGS to TRUE (1) entails a larger execution time.

STEP 2-1: Run Komondor simulator with intelligent agents

Alternatively, and in order to indicate the usage of agents, the console input must add the following extra information:

$ ./komondor_main INPUT_FILE_NODES INPUT_FILE_AGENTS OUTPUT_FILE_LOGS FLAG_SAVE_NODE_LOGS FLAG_SAVE_AGENT_LOGS FLAG_PRINT_SYSTEM_LOGS FLAG_PRINT_NODE_LOGS FLAG_PRINT_AGENT_LOGS SIM_TIME SEED

The agents operation has been summarized at README_agents.

Input files

There is an input file that is required for basic Komondor's execution. Input files are located at the "input" folder:

Apart from the input nodes file, different models are loaded through the "config_models" file (located here).

Regarding the output ("output" folder), some logs and statistics are created at the end of the execution.

Other installations

Debugging:

$ apt-get install gdb valgrind 

Validation

Komondor v.2.0 has been validated by means of ns-3 and SF-CTMN and Bianchi analytical models. The presentation of the validation can be found at "S. Barrachina-Muñoz, F. Wilhelmi, I. Selinis & B. Bellalta. Komondor: a Wireless Network Simulator for Next-Generation High-Density WLANs. 2018". Additional resources are available in this repository, in folder /Documentation/Validation. Files used for each simulation tool can be found: 1) ns-3: execution script and instructions, together with the simulation environment used for validation. 2) Komondor: input "nodes" and "system" files. Release pointing to v.2.0 must be used. 3) SF-CTMN: simulation environment, to be executed through the SF-CTMN framework, available at https://github.com/sergiobarra/SFCTMN 4) Bianchi: Matlab files emulating the Bianchi model ("Bianchi, G., Fratta, L., & Oliveri, M. (1996, October). Performance evaluation and enhancement of the CSMA/CA MAC protocol for 802.11 wireless LANs. In Personal, Indoor and Mobile Radio Communications, 1996. PIMRC'96., Seventh IEEE International Symposium on (Vol. 2, pp. 392-396). IEEE.") can be found, which simulate the throughput achieved by each WLAN in each of the proposed scenarios.

Regression test

An automated regression test is available to ensure that the development of new features does not affect to the previous implementation, which was validated in Barrachina-Muñoz, S., Wilhelmi, F., Selinis, I., & Bellalta, B. (2019, April). Komondor: a Wireless Network Simulator for Next-Generation High-Density WLANs. In 2019 Wireless Days (WD) (pp. 1-8). IEEE.

In order to execute the regression test, go to ./Komondor/Code/input and run the script named "script_regression_validation_scenarios.sh". This script will take the inputs from the "validation" folder, execute the corresponding simulations, and compare the output with the expected results (i.e., the results obtained for the aforementioned paper).

The output of the regression test will be displayed by console. In case of success, the following output should be observed:

Before executing the regression test, it is important to ensure that "simulation_ix_output_script" in config_models is set to 10 and "path_loss_model" to 4.

Academic/Education projects

One of the main purposes of Komondor is to serve as an academic/educational tool. In what follows, we list the projects in which Komondor has been used as a simulation tool:

Contribute

If you want to contribute, please contact to [email protected] and/or [email protected]

More details in CONTRIBUTING.md

Acknowledgements

This work has been partially supported by a Gift from the Cisco University Research Program (CG#890107, Towards Deterministic Channel Access in High-Density WLANs) Fund, a corporate advised fund of Silicon Valley Community Foundation.