HXAI-5G-Handover

HXAI-5G-Handover is a QLoRA adapter for Qwen/Qwen2.5-1.5B-Instruct. Given a 5G handover simulation configuration, it generates a JSON prediction of expected network outcomes. It was trained on ns-3 5G handover simulation data.

Model Details

Model Description

  • Developed by: Ramitha2002, HXAI research project
  • Model type: QLoRA adapter for a causal language model
  • Language(s): English instructions and JSON numerical output
  • Finetuned from: Qwen/Qwen2.5-1.5B-Instruct
  • License: Not declared for this adapter. Confirm a licence for the adapter and training data before reuse or redistribution.

Model Sources

Uses

Direct Use

Use the model to estimate outcomes for an ns-3-like 5G handover scenario before running a comparable simulation. Provide the settings listed below and request one JSON object only.

Input settings:

  • Cell spacing, gNB count, UE count, and UE speed
  • Route, propagation condition, and shadowing
  • Time-to-trigger (TTT), hysteresis, CIO, and ideal-RRC setting
  • Traffic type and offered Mbps

Output fields:

  • goodput_mbps, packet_loss_fraction
  • pingpongs, pingpong_per_successful_ho
  • radio_link_failures, ho_attempts, ho_successes
  • handover_delay_ms_mean, worst_ue_rx_gap_s

Downstream Use

The adapter may support experiment planning, scenario comparison, and educational analysis of simulated handover settings. It can be integrated into a tool that proposes simulation configurations, provided its estimates are clearly labelled as predictions.

Out-of-Scope Use

Do not use this adapter as a replacement for a live cellular-network controller, safety-critical decision system, real-world radio measurement system, or full ns-3 simulation. It was trained on a limited, simulator-generated dataset and does not establish real-network performance.

Bias, Risks, and Limitations

The training records come from a selected set of ns-3 scenarios. Predictions may not generalize to other network topologies, mobility patterns, radio models, traffic conditions, simulator versions, or operational networks. The final dataset combines multiple simulator/source revisions, which further limits strong reproducibility claims.

The model is strongest for goodput and less reliable for exact handover counts, ping-pong counts, and worst packet-reception gaps. It may underestimate some count-based outcomes.

Recommendations

Treat output as an exploratory estimate. Validate decisions with the simulator or measured network data. Report the held-out test results and uncertainty rather than presenting predictions as ground truth.

How to Get Started with the Model

import torch
from peft import PeftModel
from transformers import AutoModelForCausalLM, AutoTokenizer

base_id = "Qwen/Qwen2.5-1.5B-Instruct"
adapter_id = "ramitha2002/HXAI-5G-Handover"

tokenizer = AutoTokenizer.from_pretrained(adapter_id)
base = AutoModelForCausalLM.from_pretrained(
    base_id, torch_dtype=torch.float16, device_map="auto"
)
model = PeftModel.from_pretrained(base, adapter_id)

settings = {
    "cell_spacing_m": 300, "gnb_count": 3, "ue_count": 1,
    "speed_kmh": 60, "route": "line", "condition": "LOS",
    "shadowing": False, "ttt_ms": 128, "hysteresis_db": 3,
    "cio_db": 1, "ideal_rrc": False, "traffic": "constant",
    "offered_mbps": 1.0,
}
messages = [
    {"role": "system", "content": "You are a 5G handover simulation outcome predictor. Given only the simulation settings, return one valid JSON object and no extra text."},
    {"role": "user", "content": f"Predict outcomes for these simulation settings:\n{settings}"},
]
inputs = tokenizer.apply_chat_template(messages, add_generation_prompt=True, return_tensors="pt").to(model.device)
outputs = model.generate(inputs, max_new_tokens=160, do_sample=False)
print(tokenizer.decode(outputs[0][inputs.shape[1]:], skip_special_tokens=True))

Training Details

Training Data

The final dataset contains 1,753 ns-3 5G handover simulation records. Each record represents one scenario-level outcome. Data were split before training into 1,096 training records, 219 validation records, and 438 held-out test records. Repeated versions of a source run were kept in one split.

Training Procedure

Each training example contained a system instruction, scenario settings, and a JSON target containing simulator outcomes. Loss was calculated only on the JSON answer tokens.

Training Hyperparameters

  • Training regime: QLoRA with 4-bit NF4 base-model loading and FP16 computation
  • Epochs: 3
  • Learning rate: 2e-4
  • Batch size: 2
  • Gradient accumulation: 8
  • Maximum sequence length: 512
  • LoRA rank / alpha / dropout: 16 / 32 / 0.05
  • Trainable parameters: 18,464,768 of 1,562,179,072 (1.182%)
  • Random seed: 20261106

Speeds, Sizes, Times

Training took approximately 20 minutes and 31 seconds on a Google Colab Tesla T4 GPU with 15 GB VRAM. Validation loss improved from 0.2502 after epoch 1 to 0.2124 after epoch 3.

Evaluation

Testing Data, Factors & Metrics

Testing Data

Evaluation used the 438-record held-out test split. The test records were not passed to the training or validation process.

Factors

Testing covered the dataset's selected combinations of mobility, cell spacing, gNB/UE count, channel condition, traffic profile, and handover parameters. Results are not disaggregated by each factor in this release.

Metrics

Every test scenario was given to the model as settings only. The model then generated a deterministic JSON prediction. Mean absolute error (MAE), root mean squared error (RMSE), and bias were calculated against the hidden simulator outcomes. Lower MAE and RMSE are better. Bias below zero indicates underprediction.

Results

All 438 predictions were valid JSON (100% valid JSON rate).

Outcome MAE RMSE Bias
Goodput (Mbps) 0.0326 0.0860 +0.0266
Packet-loss fraction 0.0219 0.0574 -0.0181
Ping-pong count 1.7420 3.0860 -0.2860
Ping-pong rate per successful handover 0.0683 0.1173 -0.0178
Radio-link failures 0.3767 0.9079 -0.0890
Handover attempts 1.8760 3.2140 -0.3410
Successful handovers 1.8760 3.2140 -0.3410
Mean handover delay (ms) 2.8103 4.8662 -2.3556
Worst UE reception gap (s) 3.1270 8.6420 -0.7840

Compared with a baseline that always predicts the training-set average, the adapter reduced MAE for every target. Reductions were 91.8% for goodput, 74.2% for ping-pong rate, 71.7% for handover attempts/successes, and 27.7% for mean handover delay.

Model Examination

No interpretability study has been completed. The model card reports predictive outcomes only.

Environmental Impact

  • Hardware Type: Google Colab Tesla T4 GPU (15 GB VRAM)
  • Hours used: Approximately 0.34 GPU hours for fine-tuning; base-model download and evaluation are additional.
  • Cloud Provider: Google Colab
  • Compute Region: Not recorded
  • Carbon Emitted: Not measured

Technical Specifications

Model Architecture and Objective

The adapter modifies Qwen2.5-1.5B-Instruct using LoRA layers in attention and MLP projection modules. The objective is causal language modelling of the expected JSON outcome conditioned on the scenario settings.

Compute Infrastructure

Hardware

Google Colab Tesla T4 GPU with 15 GB VRAM.

Software

Python, PyTorch, Transformers, PEFT, BitsAndBytes, and Datasets.

Citation

No paper has been published for this adapter. Cite the Hugging Face model repository and this model card until a project paper is available.

Glossary

  • gNB: 5G base station.
  • UE: User equipment, such as a phone or modem.
  • Handover: Moving a UE connection from one gNB to another.
  • Ping-pong: A UE moves back to a previous cell shortly after a handover.
  • MAE: Average absolute difference between predicted and true values.
  • QLoRA: Efficient fine-tuning that keeps the base model in 4-bit form and trains small LoRA adapter weights.

Model Card Authors

Ramitha2002, HXAI research project.

Model Card Contact

Hugging Face user: ramitha2002

Downloads last month
23
Inference Providers NEW
This model isn't deployed by any Inference Provider. ๐Ÿ™‹ Ask for provider support

Model tree for ramitha2002/HXAI-5G-Handover

Adapter
(1,773)
this model