File size: 8,662 Bytes
793534c
 
 
 
 
104b47a
 
 
 
 
 
793534c
 
268fe77
104b47a
793534c
104b47a
793534c
 
 
 
 
104b47a
 
 
 
 
793534c
104b47a
793534c
104b47a
 
 
793534c
 
 
 
 
104b47a
793534c
104b47a
793534c
104b47a
 
 
 
793534c
104b47a
793534c
104b47a
 
 
 
793534c
104b47a
793534c
104b47a
793534c
104b47a
 
 
793534c
 
 
104b47a
793534c
104b47a
793534c
 
 
104b47a
793534c
 
 
104b47a
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
793534c
 
 
 
 
104b47a
793534c
 
 
104b47a
793534c
 
 
104b47a
 
 
 
 
 
 
 
 
793534c
104b47a
793534c
104b47a
793534c
 
 
 
 
 
 
104b47a
793534c
 
 
104b47a
793534c
 
 
104b47a
793534c
 
 
104b47a
793534c
104b47a
 
 
 
268fe77
104b47a
 
268fe77
 
104b47a
268fe77
793534c
104b47a
793534c
104b47a
793534c
104b47a
793534c
 
 
104b47a
 
 
 
 
793534c
104b47a
793534c
 
 
104b47a
793534c
 
 
 
 
104b47a
793534c
 
 
104b47a
793534c
104b47a
793534c
104b47a
793534c
104b47a
793534c
104b47a
 
 
 
 
 
793534c
104b47a
793534c
104b47a
793534c
 
 
104b47a
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
---
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`