NS-3 5G V2V Energy Simulator

A framework to run NS-3 simulations for V2V (vehicle-to-vehicle) scenarios and analyze radio interface energy consumption using an external module.

It uses a minimal modified version of the 5G-LENA module (v2x-v0.3.y branch) available at https://github.com/gti-uvigo/nr-v2v-energy-sim

Contents

• Overview
• Features
• Requirements
• Quick Start
• Installation (Docker and native)
• Running simulations
• Energy analysis (module: energy-analyzer)
• Input data format
• Power consumption model
• Project structure
• Troubleshooting
• License

Overview

This repository bundles simulation code (examples in scratch/energy-sim) and a Python-based analysis module (energy-analyzer) to compute energy consumption and efficiency from NS-3 simulation logs.

It uses a minimal modified version of the 5G-LENA module, refered as a submodule in contrib/nr (v2x-v0.3.y branch). Please ensure git submodules are initialized.

git submodule update --init --recursive

or git clone --recursive

Requirements

• Linux (tested on Ubuntu/Debian) or Docker environment
• NS‑3 source tree (e.g., ns-3-dev) — tested with NS-3 v3.41 (Provided in this repo)
• Python >= 3.7
• Python packages (use virtualenv):
  • pandas
  • numpy
  • matplotlib
  • seaborn

Tested with

• NS-3 v3.41
• 5g-lena (contrib/nr) v2x-v0.3.y

Quick Start

1. Build or prepare NS‑3 (v3.41) so the ./ns3 helper is available in ns-3-dev/.
2. Run the example scenarios from scratch/energy-sim:

cd ns-3-dev
./ns3 run "scratch/energy-sim/main.cc --configPath=./scratch/energy-sim/1"
./ns3 run "scratch/energy-sim/main.cc --configPath=./scratch/energy-sim/2"

3. Archive outputs between runs to avoid overwriting:

mv output/ output-first
mv output/ output-second

4. Run the energy analysis from the repository root:

python3 energy-analyzer/analyze.py --exp1-dir ./ns-3-dev/output-first \
                                   --exp2-dir ./ns-3-dev/output-second \
                                   --output-dir ./results --verbose

5. Check results in results/ (plots and CSV summaries).

Installation

Two recommended approaches: Docker (reproducible) or native installation.

Docker

• Build the image from the repository root:

  docker build -t ns3-energy-analysis .

• Run an interactive container with the workspace mounted:

  docker run --rm -v "$(pwd):/workspace" -it ns3-energy-analysis /bin/bash

Inside the container you can build NS‑3 or run the analysis scripts directly.

Native (Ubuntu/Debian) — minimal install:

sudo apt update
sudo apt install -y build-essential git python3 python3-pip pkg-config g++-11 cmake
pip3 install --user -r energy-analyzer/requirements.txt

Adjust system packages as required by your NS‑3 build (see Dockerfile).

Running simulations

1. Prepare or build NS‑3. This project has been tested with NS‑3 v3.41 and expects the 5G-LENA modified version in contrib/nr.
2. Run the energy-sim examples located under scratch/energy-sim (note: energy-sim is not in the repository root; it lives under scratch):

cd ns-3-dev
./ns3 run "scratch/energy-sim/main.cc --configPath=./scratch/energy-sim/1"
./ns3 run "scratch/energy-sim/main.cc --configPath=./scratch/energy-sim/2"

3. After each run, move or archive the output folder to avoid overwriting:

mv output/ output-first
mv output/ output-second

Energy analysis

The analysis module is located in energy-analyzer/. Performs the following tasks:

• Parses simulation output logs
• Parses node state change logs
• Computes energy consumed per node and per run
• Computes energy efficiency (bits/J)
• Produces plots and CSV summaries

Basic usage:

# from repository root
python3 energy-analyzer/analyze.py --verbose
# Example with custom directories
python3 energy-analyzer/analyze.py --exp1-dir ./ns-3-dev/output-first --exp2-dir ./ns-3-dev/output-second --output-dir ./results --verbose

Input data format

The analysis expects CSV files named with this convention:

• State change files: state-change_t{sim_time}_v{num_vehicles}_ps{pkt_size}_int{interval}_st{start_time}_sp{stop_time}_seed{seed}.csv Required columns:

  • NodeId
  • Timestamp (seconds)
  • OldState (int)
  • NewState (int)

• Data reception files: multicast_rx_t{sim_time}_v{num_vehicles}_ps{pkt_size}_int{interval}_st{start_time}_sp{stop_time}_seed{seed}.csv Required columns:

  • RxBytes

State mapping used by the analyzer (example):

0: IDLE
1: TX
2: RX_DATA
3: RX_DL_CTRL
4: RX_UL_CTRL
5: RX_UL_SRS
6: CCA_BUSY

Power consumption model

Default power values (Watts) used in analysis — configurable in code:

POWER_CONSUMPTION = {
    'tx_power': 0.2,
    'rx_power': 0.15,
    'idle_power': 0.05,
    'cca_busy_power': 0.07,
}

Energy (J) is computed by integrating power over time spent in each state.

Project structure

Relevant folders and files:

ns-3-dev/
├── scratch/                # examples and user programs
│   └── energy-sim/         # V2V energy simulator folder
│       ├── main.cc         # main simulation program
│       ├── CMakeLists.txt  # CMake configuration for energy-sim (Include dependencies for configuration reading)
│       ├── 1/              # example scenario 1
│       └── 2/              # example scenario 2
├── energy-analyzer/        # Python analysis and visualization scripts (energy analysis module)
├── results/                # analysis outputs (plots, CSVs)
├── contrib/                # contrib modules (e.g. nr / 5g-lena)
│   └── nr/                 # 5G-LENA (v2x-v0.3.y branch, modified)
(...)                       # other ns-3 folders (src/, examples, etc.) 
├── Dockerfile              # Dockerfile 
└── README.md

Citation

If you use this code in your research, please cite: (TODO: Add citation details here, when available)

License

This project is distributed under the GPL‑v2 license (see LICENSE), like ns-3 and 5G-LENA. We want to thank the ns-3 and 5G-LENA communities for their work in which this project is based.