Text Generation
PEFT
Safetensors
5g
handover
telecommunications
qlora
lora
simulation
conversational
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
|
Download README.md from ramitha2002/HXAI-5G-Handover: direct link, hf CLI and curl.
- Browser
- Download file 8.66 kB
-
https://huggingface.co/ramitha2002/HXAI-5G-Handover/resolve/main/README.md
- Command line
-
hf download hf://ramitha2002/HXAI-5G-Handover/README.md
-
curl -L -o README.md https://huggingface.co/ramitha2002/HXAI-5G-Handover/resolve/main/README.md
8.66 kB
| base_model: Qwen/Qwen2.5-1.5B-Instruct | |
| library_name: peft | |
| pipeline_tag: text-generation | |
| tags: | |
| - 5g | |
| - handover | |
| - telecommunications | |
| - qlora | |
| - lora | |
| - simulation | |
| # 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](https://huggingface.co/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_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 | |
| ```python | |
| 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` | |