Instructions to use ramitha2002/HXAI-5G-Handover with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- PEFT
How to use ramitha2002/HXAI-5G-Handover with PEFT:
from peft import PeftModel from transformers import AutoModelForCausalLM base_model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-1.5B-Instruct") model = PeftModel.from_pretrained(base_model, "ramitha2002/HXAI-5G-Handover") - Notebooks
- Google Colab
- Kaggle
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
- Repository: https://huggingface.co/ramitha2002/HXAI-5G-Handover
- Paper: Not available at the time of publication.
- Demo: Not available.
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_fractionpingpongs,pingpong_per_successful_horadio_link_failures,ho_attempts,ho_successeshandover_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
- 21