5g-handover-sim

End-to-end Handover Simulator for 5G Heterogeneous Network Enviroments

Introduction

This repository contains a 5G HetNet Simulator designed to evaluate the performance of various handover algorithms in heterogeneous network environments. The simulator is built on top of the ns-3 network simulator and leverages the 5G-LENA module for realistic end-to-end network simulations.

It provides a framework for simulating handover scenarios with arbitrary handover algorithms, allowing to test and compare different approaches to handover management in 5G networks.

Tested on:

• ns-3 3.41
• 5G-LENA 3.x.y

To run the simulator, you will need to have ns-3 and 5G-LENA installed. Please refer to the 5G-LENA documentation for detailed instructions on how to set up ns-3 and 5G-LENA.

The rest of the instructions on how to install and run the simulator expect you to have a working installation of ns-3 and 5G-LENA in the root directory of the repository, specifically in the ns-3-dev folder.

Note: As part of the installation process, please remember to create a symbolic link from the network-simulator folder into the ns-3-dev/scratch folder.

ln -s /path/to/network-simulator /path/to/ns-3-dev/scratch

Code structure

Network Simulator (network-simulator/)

The first part of the code is implemented using C++ and is based on the ns-3 network simulator, specifically the 5G-LENA module. This part of the code is responsible for simulating the low-level network behavior, including the generation of traces and performance metrics.

Handover Simulator (handover-simulator/)

The second part of the code is implemented using Python. This part focuses on high-level simulation and algorithm evaluation for handover scenarios.

This code provides an interface to configure and run simulations, analyze the simulation results, and evaluate different handover algorithms. They leverage the output generated by the network simulator,

In this folder there are several subfolders, src/ for the source code, sc/ for the scenario definition files, waypoints for the waypoint and movement definition files, traces/ with the traces of the ns-3 simulations and the results of the high level simulation. If traces folder are not present the handover simulator will generate them automatically.

The results of the handover simulation are stored inside the specific trace folder, in a subfolder named results/. Each algorithm has its own subfolder, and the results are stored in CSV files.

The handover simulator implements four different handover algorithms:

1. 3GPP Rel.15 based Algorithm: This is the standard handover algorithm defined by 3GPP for 5G networks.
2. 3GPP Rel.16 Conditional Handover (CHO): This algorithm is implementation of the Conditional Handover mechanism introduced in 3GPP Release 16.
3. Score Based Greedy Handover (SBGH): This proposed algorithm selects the target cell based on a scoring mechanism that takes into account various factors such as signal strength, bandwidth, and cell load.
4. Multi-agent DDQN based Handover: This algorithm leverages a multi-agent Double Deep Q-Network (DDQN) approach to optimize handover decisions.

Note: SBGH and the Multi Agent DDQN Based Handover are described in the associated publication (see Citation).

Interaction between Parts

1. The network simulator generates traces and performance metrics during the simulation of the 5G HetNet environment.
2. The handover simulator reads these traces and metrics, allowing for high-level analysis and evaluation of different handover algorithms.
3. The handover simulator evaluates the performance of the handover algorithms based on the traces generated by the network simulator.

   Setting up the environment:

   You can set the environment in two ways:

4. Using Docker
5. Native

1. Using Docker

1. execute docker-compose in the root directory:

   docker-compose up -d
   

2. Make sure the following dependencies are installed:
   • Docker
   • Docker Compose

3. Please refer to the Docker installation guide and the Docker Compose installation guide for your specific distribution.

4. Ensure that the Docker services are up and running. You can check the status of the services by running:

   sudo systemctl status docker.service
   

   sudo systemctl status docker.socket
   

   The user should be added to the Docker group to interact without root privileges

   sudo usermod -aG docker $USER
   

   2.Native

   Please refer to the 5G-LENA documentation for detailed instructions on how to set up ns-3 and 5G-LENA.

Building and Running the Project

To build and run the project, follow these instructions:

1. Open a terminal and navigate to the ns3-dev folder:

cd ns3-dev

1. Configure the build profile for optimized building by running the following command:

./ns3 configure --build-profile=optimized

1. Once the build process is complete, navigate to the handover-simulator folder:

   cd ../handover-simulator/src
   

2. Start the handover simulator by running the following command:

   python3 main.py
   

Usage

The handover simulator can be run from the command line. To start the simulator, navigate to the handover-simulator/src directory and run the following command:

python3 main.py

The simulator accepts several command-line arguments. If an argument is not specified, the simulator will assume its default value. To see the list of available arguments and their default values, run:

python3 main.py --help

Scenario Definition File

The scenario definition files provide the parameters for the ns-3 simulation. The file is structured in several sections:

1. Scenario dimensions: This section defines the dimensions of the simulation environment. The format is !MinX MaxX MinY MaxY.

2. Bands data: This section defines the frequency bands used in the simulation. Each band is represented by a line starting with * followed by the band ID, central frequency in Hz, user bandwidth in Hz, and gNB bandwidth in Hz.

3. gNodeB Data: This section defines the new gNodeBs (gNBs) used in the simulation. Each gNB is represented by a line containing the gNB ID, its position (X, Y, Z coordinates), the band it uses, its transmission power in dBm, and its radiation pattern (I for isotropic, H Hexagonal trisector pattern).

Each gNB is defined in the format: GNB_ID Position_X Position_Y Position_Z Band_ID Transmission_Power_dBm gNB_Type.

# is used to denote single line comments, the parser will ignore it.

This as an example here is the sc.txt file that can be found in the handover-simulator/sc/ folder

# Scenario definition file

# Scenario dimensions 
# MinX MaxX MinY MaxY
!-400 400 -200 200

# Bands data
# * Band_ID Central_Frequency_Hz User_Bandwidth_Hz GNB_Bandwidth_Hz
*0 3.5e9 20e6 400e6
*1 28e9 100e6 400e6

# gNodeB Data for Micro Line (Band 1)
# Format: GNB_ID Position_X Position_Y Position_Z Band_ID Transmission_Power_dBm gNB_Type
0 -200.0 50.0 3.0 1 23.0 I
1 -200 -50.0 3.0 1 23.0 I
2 0.0 50.0 3.0 1 23.0 I
3 0.0 -50.0 3.0 1 23.0 I
4 200.0 50.0 3.0 1 23.0 I
5 200 -50.0 3.0 1 23.0 I

# gNodeB Data for Macro Line (Band 0)
# Format: GNB_ID Position_X Position_Y Position_Z Band_ID Transmission_Power_dBm gNB_Type
6 0 150.0 20.0 0 53.0 H
7 0 -150.0 20.0 0 53.0 H

Output format

The output format of the traces of ns-3 is a CSV for each simulation. In a simulation with n UEs and m GNBs, there are n*m simulations. Each simulation can be found in <trace folder>/<number of node>/<number of gnb>/traces.csv

In the subfolder <trace folder>/results/, several folders can be found, one for each algorithm of handover.

License

This repository contains two functional components, each under a different license:

• The handover simulator is distributed under the MIT License. The DDQN Agent code is based on code from PacktPublishing/Advanced-Deep-Learning-with-Keras.
• The network simulator is distributed under the GNU General Public License v2 (GPL-2.0). It is based on code examples from 5G-LENA.

Citation

If you use this code in your research, please cite the following paper:

@ARTICLE{rua2026intelligent,
  author={Rúa-Estévez, José Manuel and Fondo-Ferreiro, Pablo and Gil-Castiñeira, Felipe and González-Castaño, Francisco Javier},
  journal={IEEE Open Journal of the Communications Society}, 
  title={Intelligent Handover Solutions for Heterogeneous B5G Cellular Networks: Proposals and Full-Stack Evaluation}, 
  year={2026},
  volume={7},
  number={},
  pages={1-19},
  keywords={Handover;5G mobile communication;Millimeter wave communication;Standards;Load modeling;Signal to noise ratio;3GPP;Optimization;Macrocell networks;Heuristic algorithms;5G;B5G;deep learning;handover;heterogeneous networks;HetNets;reinforcement learning;simulation environment},
  doi={10.1109/OJCOMS.2025.3649168}}