handoverlab 2.4.2__tar.gz → 2.5.0__tar.gz

handoverlab-2.5.0/.zenodo.json

@@ -0,0 +1,39 @@
+{
+  "title": "HandoverLab: system-level handover simulator for 5G-Advanced and beyond-5G research",
+  "description": "HandoverLab is a reproducible system-level simulator for studying and comparing handover algorithms and procedures in 5G-Advanced, beyond-5G and some NTN scenarios, with explicit models, optional features and a documented validation scope. It is open source and simulates 3GPP mobility procedures (baseline handover with Event A3, Release-16 conditional and DAPS handover, Release-18 L1/L2-triggered mobility, conditional handover with the location events of Release 18, dual connectivity) for many users in dense 5G-Advanced and beyond-5G networks, on a street grid, in an open area, along a highway or a high-speed railway, in an indoor office, in suburban and rural macro cells or under the earth-moving beams of a LEO satellite. It provides a TR 38.901 received-power radio model (TR 38.811 for the satellite) with optional TDL fast fading, SSB and UE receive beams and several carriers, an optional slot scheduler with MCS, TBS and HARQ and user-plane buffers at handover, an L3-filtered measurement chain, a radio-link failure model, an outcome label for every handover attempt, a plug-in interface for handover rules (including a measurement-prediction rule after TR 38.744), equal-budget tuning studies with paired statistics, and verification against hand-computed values, golden event-log fingerprints, the 3GPP large-scale calibration and ns-3 / 5G-LENA.",
+  "upload_type": "software",
+  "access_right": "open",
+  "license": "MIT",
+  "creators": [
+    {
+      "name": "Jalili Sanjarani, Mostafa"
+    },
+    {
+      "name": "Elmi Sola, Yasser"
+    }
+  ],
+  "keywords": [
+    "handover",
+    "conditional handover",
+    "mobility",
+    "mobility robustness",
+    "radio-link failure",
+    "system-level simulation",
+    "5G",
+    "beyond 5G",
+    "3GPP",
+    "Python",
+    "dual connectivity",
+    "fast fading",
+    "beam management",
+    "NTN",
+    "AI/ML mobility"
+  ],
+  "related_identifiers": [
+    {
+      "identifier": "https://github.com/mjs19971997/handoverlab",
+      "relation": "isSupplementTo",
+      "scheme": "url"
+    }
+  ]
+}

{handoverlab-2.4.2 → handoverlab-2.5.0}/CHANGELOG.md

@@ -7,6 +7,57 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [2.5.0] - 2026-10-25
+
+No change of defaults or results: every golden fingerprint is unchanged.
+
+### Added
+
+- The ns-3 comparison setting as code: `handoverlab.verify.ns3.COMPARISON_SETTING`
+  (`{"protocol.lm_load": 0.15, "protocol.exec_can_fail": False}`: interferer load 0.15 at link monitoring,
+  ideal execution), applied by `scenario_for(..., comparison=True)`, `compare(..., comparison=True)` and
+  `holdout(..., comparison=True)` (after the in-car loss, before `overrides`), by
+  `ns3_checks(..., comparison=True)` and `run_verify(..., ns3_comparison=True)` together with the in-car loss
+  of ns-3, and on the command line by `handoverlab verify --ns3 --ns3-comparison`. The summary of `compare`
+  records `car` and `comparison`. It is not a default.
+
+### Validation
+
+- An independent validation study, registered before any of its runs, with one amendment fixed before the runs
+  of its second part; nothing tuned on its data (`docs/calibration.md`, "Independent validation study (2.5.0)").
+- **V1, failure rate against 40 fresh ns-3 / 5G-LENA runs** (site distance 200 / 300 m, 10 / 28 m/s,
+  time-to-trigger 80 / 320 ms, seeds 401-405). The N3 candidate, not re-tuned (`lm_load` 0.15, ideal
+  execution, in-car loss): failure level 0.97 of ns-3 (limit 0.67-1.5), rank correlation 0.88 over the 8 cells,
+  handover-rate ratio 0.965, TTT direction in 4 of 4: all pass, so it becomes the documented ns-3 comparison
+  setting. The 2.4.2 link monitoring with ideal execution: level 0.33 (fails), rank 0.84, ratio 0.973. V1 has
+  time-to-trigger 80 and 320 ms only; on the earlier fresh set N3 the same setting failed the level (0.47): its
+  TTT 100 ms cells matched, its TTT 640 ms cells had about half of ns-3's failures (matching at 100 ms was not a
+  registered criterion).
+- **V2, generalisation of the adaptive and learning rules** (tuned and trained on `urban-grid-10ghz`, seeds
+  101-104; tested on `ns3-urban-3.5ghz`, `urban-macro-tr37885-4ghz`, `highway-tr37885-4ghz` and
+  `fr3-urban-15ghz`, seeds 501-505, against tuned A3). `a3_mro` and `dqn` generalise (fewer unnecessary
+  handovers on all four test cards, no cost flag). `a3_bandit` meets the registered criteria only formally: it
+  has more unnecessary handovers than tuned A3 on every card (+1.644 per UE-minute on the training card) and
+  1.65 to 4.15 times its ping-pong on three test cards. `a3_pred` does not generalise (the gain is lost on
+  `urban-macro-tr37885-4ghz`, and it cannot run at the 0.2 s measurement period of `ns3-urban-3.5ghz`). Limits
+  of the design: with 5 seeds the no-harm criterion cannot fail (smallest Wilcoxon p 0.0625), and
+  `fr3-urban-15ghz` is the least independent test card.
+
+### Documentation
+
+- The failure level is now stated precisely everywhere it was called "not calibrated" (README, scenario cards,
+  `docs/comparison.md`, `docs/verification.md`, the user guide and the guides): the ns-3
+  comparison setting passed the pre-registered checks on one fresh set of ns-3 runs (V1, TTT 80 and 320 ms:
+  level 0.97, rank 0.88) and failed the level on another (N3: 0.47, because of its TTT 640 ms cells); the
+  default link-monitoring model gives a third to a sixth of ns-3's level (0.33 on V1, 0.16 on N3). Scenario
+  pages regenerated.
+- The learning-rule and AI/ML-mobility guides: the generalisation results of V2.
+- README, `CITATION.cff` and `.zenodo.json` describe HandoverLab as a reproducible system-level simulator for
+  studying and comparing handover algorithms and procedures in 5G-Advanced, beyond-5G and some NTN scenarios,
+  with explicit models, optional features and a documented validation scope.
+- Citation with the DOI of 2.4.2 (10.5281/zenodo.23589215).
+- Command-line reference: `verify --ns3-comparison`. Dashboard screenshots retaken with this version.
+
 ## [2.4.2] - 2026-10-23
 
 No change of results.
@@ -1120,7 +1171,8 @@ First alpha release (stage 1: the core simulator).
 - Documentation: README, user guide, contribution guide, citation file; CI on Linux, Windows and
   macOS with Python 3.9-3.12.
 
-[Unreleased]: https://github.com/mjs19971997/handoverlab/compare/v2.4.2...HEAD
+[Unreleased]: https://github.com/mjs19971997/handoverlab/compare/v2.5.0...HEAD
+[2.5.0]: https://github.com/mjs19971997/handoverlab/compare/v2.4.2...v2.5.0
 [2.4.2]: https://github.com/mjs19971997/handoverlab/compare/v2.4.1...v2.4.2
 [2.4.1]: https://github.com/mjs19971997/handoverlab/compare/v2.4.0...v2.4.1
 [2.4.0]: https://github.com/mjs19971997/handoverlab/compare/v2.3.0...v2.4.0

{handoverlab-2.4.2 → handoverlab-2.5.0}/CITATION.cff

@@ -2,8 +2,10 @@ cff-version: 1.2.0
 message: "If you use this software, please cite it as below."
 title: "HandoverLab: system-level handover simulator for 5G-Advanced and beyond-5G research"
 abstract: >-
-  HandoverLab is an open-source, system-level simulator of 3GPP mobility procedures (baseline
-  handover with Event A3, Release-16 conditional and DAPS handover, Release-18 L1/L2-triggered
+  HandoverLab is a reproducible system-level simulator for studying and comparing handover
+  algorithms and procedures in 5G-Advanced, beyond-5G and some NTN scenarios, with explicit models,
+  optional features and a documented validation scope. It is open source and simulates 3GPP
+  mobility procedures (baseline handover with Event A3, Release-16 conditional and DAPS handover, Release-18 L1/L2-triggered
   mobility, conditional handover with the location events of Release 18) for many users in dense
   5G and beyond-5G networks, on a street grid, in an open area, along a highway, indoors, in rural
   cells, along a high-speed railway or under the earth-moving beams of a LEO satellite. It provides a
@@ -14,7 +16,7 @@ abstract: >-
   handover rules (including a measurement-prediction rule after TR 38.744), equal-budget tuning
   studies with paired statistics, and verification against hand-computed values, golden event-log
   fingerprints, the 3GPP large-scale calibration and ns-3 / 5G-LENA.
-version: "2.4.2"
+version: "2.5.0"
 doi: 10.5281/zenodo.23409131
 identifiers:
   - type: doi
@@ -32,7 +34,10 @@ identifiers:
   - type: doi
     value: 10.5281/zenodo.23585308
     description: "Version 2.4.1 on Zenodo"
-date-released: 2026-10-23
+  - type: doi
+    value: 10.5281/zenodo.23589215
+    description: "Version 2.4.2 on Zenodo"
+date-released: 2026-10-25
 license: MIT
 repository-code: "https://github.com/mjs19971997/handoverlab"
 url: "https://mjs19971997.github.io/handoverlab/"

{handoverlab-2.4.2 → handoverlab-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: handoverlab
-Version: 2.4.2
+Version: 2.5.0
 Summary: System-level handover simulator for 5G-Advanced and beyond-5G research
 Author: Mostafa Jalili Sanjarani, Yasser Elmi Sola
 License-Expression: MIT
@@ -60,7 +60,7 @@ Dynamic: license-file
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23409131.svg)](https://doi.org/10.5281/zenodo.23409131) [![PyPI](https://img.shields.io/pypi/v/handoverlab.svg)](https://pypi.org/project/handoverlab/)
 
-A system-level handover simulator for 5G-Advanced and beyond-5G research, written in Python.
+HandoverLab is a reproducible system-level simulator for studying and comparing handover algorithms and procedures in 5G-Advanced, beyond-5G and some NTN scenarios, with explicit models, optional features and a documented validation scope. It is written in Python.
 
 HandoverLab simulates 3GPP mobility procedures (baseline handover with Event A3, Release-16
 conditional handover and DAPS handover, Release-18 L1/L2-triggered mobility, conditional handover with
@@ -70,7 +70,7 @@ received-power-level radio model from TR 38.901 (TR 38.811 for the satellite) (o
 and several carriers), an L3-filtered measurement chain, a radio-link failure model, and an
 outcome label for every handover attempt.
 
-> **Status: 2.4.2** (`python -m pip install handoverlab`). The public surface (configuration and
+> **Status: 2.5.0** (`python -m pip install handoverlab`). The public surface (configuration and
 > result formats with a schema version, the rule interface, metric names, commands and the
 > documented Python names) follows the [stability policy](https://github.com/mjs19971997/handoverlab/blob/main/docs/stability.md): within 2.x it only grows,
 > and anything removed is deprecated first. 2.0.0 makes the 3GPP values the defaults (the protocol profile,
@@ -257,7 +257,7 @@ the clause-by-clause detail is in [standard compliance](https://github.com/mjs19
 | Traffic and load | constant rates per 5QI, full buffer, periodic, FTP model 3; cell load drives interference; options: a slot scheduler (`protocol.scheduler`: round robin or proportional fair) with the MCS, TBS and HARQ of TS 38.214 (since 2.2.0), and user-plane buffers at handover (`protocol.buffers`: simplified PDCP / RLC in AM or UM with Xn data forwarding, since 2.3.0) | by default the rate from the SINR (Shannon-type mapping) without a scheduler; with the scheduler the channel is held for the 10 ms step and the MCS is chosen from the SINR of one measurement interval earlier (no CSI reports); buffers: downlink only, one bearer per user, the interruption quantised to the measurement interval; both options need the base engine (no beams, layers, NTN or TS 38.133 periods) | uplink data, CSI-based link adaptation, PDCP reordering and status reports at the UE, TCP and applications |
 | Measurements | L1 samples with error, TS 38.331 L3 filter, TS 38.133 measurement periods and gaps (option) | wideband RSRP; SS-RSRP per resource element with beams/carriers | RSRQ, CSI reporting |
 | Procedures | baseline (A3), CHO, DAPS, LTM, conditional LTM, CHO with D1/D2 for satellites, A3/A5 between carriers; rules `a3`, `a3a5`, `a3_mro`, `a3_bandit`, `dqn`, `a3_pred`, `cho`, `cho_d2`, `daps`, `ltm`, `cltm` | fixed preparation, command and execution delays; re-establishment always succeeds after a fixed outage | condEventT1, RACH-less NTN handover, Xn signalling in detail |
-| Failure model | Qout/Qin with windows, N310/N311/T310, T304, command received during T310, re-establishment, link-monitoring restart | Qout/Qin as SINR thresholds (TR 36.839 values) instead of the BLER of a hypothetical PDCCH | BLER-based link monitoring; absolute failure rates are not calibrated: compare rules with each other |
+| Failure model | Qout/Qin with windows, N310/N311/T310, T304, command received during T310, re-establishment, link-monitoring restart | Qout/Qin as SINR thresholds (TR 36.839 values) instead of the BLER of a hypothetical PDCCH | BLER-based link monitoring; the absolute failure level: the ns-3 comparison setting passed the pre-registered checks on one fresh ns-3 set (TTT 80 and 320 ms) and failed the level on another (TTT 640 ms cells); the default gives a third to a sixth of ns-3's: compare rules with each other |
 | Time | 10 ms step by default (`protocol.step_s`); the effect of the step is measured in [time step](https://github.com/mjs19971997/handoverlab/blob/main/docs/time-step.md) | events rounded to the step | sub-slot timing |
 
 Built-in cards: `smoke`, `urban-grid-10ghz`, `fr3-urban-15ghz`, `urban-grid-28ghz-beams`, `dense-urban-2layer`,
@@ -326,9 +326,15 @@ The same 24 Event-A3 settings were simulated in HandoverLab and in the packet-le
 ns-3 with 5G-LENA. Handover and unnecessary-handover rates agree (median ratios 0.95 and 1.06,
 rank correlation 0.99; `handoverlab verify --ns3`, version 2.1.0). For failure rates, with the in-car loss of ns-3 and the restart of the link
 monitoring switched on, the order of settings and conditions agrees too, also on ns-3 results
-that were held back from any tuning (rank correlation 0.82-0.91). The absolute values
-differ, so compare failure rates between rules within HandoverLab. The causes are traced in
-[docs/calibration.md](https://github.com/mjs19971997/handoverlab/blob/main/docs/calibration.md). On two of them HandoverLab follows the 3GPP texts more closely
+that were held back from any tuning (rank correlation 0.82-0.91). For the failure level,
+the ns-3 comparison setting of 2.5.0 (`handoverlab.verify.ns3.COMPARISON_SETTING`: interferer load
+0.15 at link monitoring and ideal execution, with the in-car loss of ns-3;
+`handoverlab verify --ns3 --ns3-comparison`) passed the pre-registered checks on one fresh set of ns-3
+runs (V1, TTT 80 and 320 ms: level 0.97 of ns-3, rank 0.88) and failed the level on another (N3: 0.47,
+because of its TTT 640 ms cells). The default link-monitoring model gives a third to a sixth of ns-3's
+level (0.33 on V1, 0.16 on N3). The setting is not a default, so
+compare failure rates between rules within HandoverLab. The study and the causes of the differences are
+in [docs/calibration.md](https://github.com/mjs19971997/handoverlab/blob/main/docs/calibration.md). On two of the causes HandoverLab follows the 3GPP texts more closely
 than ns-3:
 
 - **In-car penetration loss.** TR 38.901 clause 7.4.3.2 gives it to a user inside a car. ns-3 adds
@@ -345,6 +351,16 @@ L1/L2-triggered mobility.
 
 ## What's new
 
+- **2.5.0**: an independent, pre-registered [validation study](https://github.com/mjs19971997/handoverlab/blob/main/docs/calibration.md#independent-validation-study-250). On 40
+  fresh ns-3 runs (V1, TTT 80 and 320 ms) the ns-3 comparison setting passed the pre-registered checks
+  (level 0.97, order 0.88); on the earlier fresh set N3 it failed the level (0.47, because of its TTT 640 ms
+  cells). It is now documented as code (`handoverlab.verify.ns3.COMPARISON_SETTING`,
+  `verify --ns3 --ns3-comparison`; not a default). Tuned on one card and tested on four unseen cards and
+  seeds, `a3_mro` and `dqn` kept fewer unnecessary handovers than tuned A3; `a3_bandit` met the criteria
+  only formally (more unnecessary handovers and ping-pong); `a3_pred` did not generalise. Limits of this
+  design: with 5 seeds the smallest two-sided Wilcoxon p is 0.0625, so the no-harm check could not fail, and
+  `fr3-urban-15ghz` is the training grid at another frequency, so it is the least independent test card
+  ([V2](https://github.com/mjs19971997/handoverlab/blob/main/docs/calibration.md#v2-do-the-adaptive-and-learning-rules-generalise)). No change of results.
 - **2.4.0**: UE receive beams (panels of TR 38.802, best beam or a sweep); a measurement-prediction rule after
   TR 38.744 (`a3_pred`: predicted Event A3 or measurement skipping, sample and hold or a trained ridge
   predictor); the slot scheduler as a compiled kernel (`run.backend: numba`, bit-identical; on the ns-3 card
@@ -569,9 +585,12 @@ the pages are plain Markdown in [docs/](https://github.com/mjs19971997/handoverl
     scheduler, the 7 GHz calibration and the comparison with other simulators.
 27. 2.4.1: pictures, citation and tutorials brought up to date; the example study
     completes again; no change of results.
-28. **2.4.2 (this release)**: every option has a picture; the dashboard pictures show the current version;
+28. 2.4.2: every option has a picture; the dashboard pictures show the current version;
     guide and tutorial examples rerun; facts made consistent; no change of results.
-29. Later (planned, not done), staying a handover simulator: the effect of a handover on what the user
+29. **2.5.0 (this release)**: an independent, pre-registered validation study: the ns-3 comparison setting
+    for the failure level (passed on one fresh set with TTT 80 and 320 ms, failed the level on N3), and the generalisation of the adaptive and learning rules to
+    unseen cards and seeds; no change of results.
+30. Later (planned, not done), staying a handover simulator: the effect of a handover on what the user
     sees (simple TCP and application models on top of the buffers), MIMO as an SINR gain, hundreds of
     users per run, and one scenario definition that also runs in ns-3; condEventT1 and earth-fixed beams.
 
@@ -581,9 +600,10 @@ If you use HandoverLab, please cite it as described in [CITATION.cff](https://gi
 it under *Cite this repository*). Every release is archived on Zenodo:
 [doi:10.5281/zenodo.23409131](https://doi.org/10.5281/zenodo.23409131) cites all versions (it resolves to
 the latest). To cite the exact version you used, take its DOI from the version list on that page, where
-the DOI of the latest version is listed; for example, version 2.4.1 is
+the DOI of the latest version is listed; for example, version 2.4.2 is
+[doi:10.5281/zenodo.23589215](https://doi.org/10.5281/zenodo.23589215), version 2.4.1
 [doi:10.5281/zenodo.23585308](https://doi.org/10.5281/zenodo.23585308) and version 2.4.0
-[doi:10.5281/zenodo.23582521](https://doi.org/10.5281/zenodo.23582521). The BibTeX entry below cites 2.4.1;
+[doi:10.5281/zenodo.23582521](https://doi.org/10.5281/zenodo.23582521). The BibTeX entry below cites 2.4.2;
 replace version and DOI with those of the version you used.
 
 ```bibtex
@@ -592,8 +612,8 @@ replace version and DOI with those of the version you used.
   title     = {{HandoverLab}: system-level handover simulator for 5G-Advanced and beyond-5G research},
   year      = {2026},
   publisher = {Zenodo},
-  version   = {2.4.1},
-  doi       = {10.5281/zenodo.23585308},
+  version   = {2.4.2},
+  doi       = {10.5281/zenodo.23589215},
   url       = {https://github.com/mjs19971997/handoverlab}
 }
 ```

{handoverlab-2.4.2 → handoverlab-2.5.0}/README.md

@@ -2,7 +2,7 @@
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23409131.svg)](https://doi.org/10.5281/zenodo.23409131) [![PyPI](https://img.shields.io/pypi/v/handoverlab.svg)](https://pypi.org/project/handoverlab/)
 
-A system-level handover simulator for 5G-Advanced and beyond-5G research, written in Python.
+HandoverLab is a reproducible system-level simulator for studying and comparing handover algorithms and procedures in 5G-Advanced, beyond-5G and some NTN scenarios, with explicit models, optional features and a documented validation scope. It is written in Python.
 
 HandoverLab simulates 3GPP mobility procedures (baseline handover with Event A3, Release-16
 conditional handover and DAPS handover, Release-18 L1/L2-triggered mobility, conditional handover with
@@ -12,7 +12,7 @@ received-power-level radio model from TR 38.901 (TR 38.811 for the satellite) (o
 and several carriers), an L3-filtered measurement chain, a radio-link failure model, and an
 outcome label for every handover attempt.
 
-> **Status: 2.4.2** (`python -m pip install handoverlab`). The public surface (configuration and
+> **Status: 2.5.0** (`python -m pip install handoverlab`). The public surface (configuration and
 > result formats with a schema version, the rule interface, metric names, commands and the
 > documented Python names) follows the [stability policy](https://github.com/mjs19971997/handoverlab/blob/main/docs/stability.md): within 2.x it only grows,
 > and anything removed is deprecated first. 2.0.0 makes the 3GPP values the defaults (the protocol profile,
@@ -199,7 +199,7 @@ the clause-by-clause detail is in [standard compliance](https://github.com/mjs19
 | Traffic and load | constant rates per 5QI, full buffer, periodic, FTP model 3; cell load drives interference; options: a slot scheduler (`protocol.scheduler`: round robin or proportional fair) with the MCS, TBS and HARQ of TS 38.214 (since 2.2.0), and user-plane buffers at handover (`protocol.buffers`: simplified PDCP / RLC in AM or UM with Xn data forwarding, since 2.3.0) | by default the rate from the SINR (Shannon-type mapping) without a scheduler; with the scheduler the channel is held for the 10 ms step and the MCS is chosen from the SINR of one measurement interval earlier (no CSI reports); buffers: downlink only, one bearer per user, the interruption quantised to the measurement interval; both options need the base engine (no beams, layers, NTN or TS 38.133 periods) | uplink data, CSI-based link adaptation, PDCP reordering and status reports at the UE, TCP and applications |
 | Measurements | L1 samples with error, TS 38.331 L3 filter, TS 38.133 measurement periods and gaps (option) | wideband RSRP; SS-RSRP per resource element with beams/carriers | RSRQ, CSI reporting |
 | Procedures | baseline (A3), CHO, DAPS, LTM, conditional LTM, CHO with D1/D2 for satellites, A3/A5 between carriers; rules `a3`, `a3a5`, `a3_mro`, `a3_bandit`, `dqn`, `a3_pred`, `cho`, `cho_d2`, `daps`, `ltm`, `cltm` | fixed preparation, command and execution delays; re-establishment always succeeds after a fixed outage | condEventT1, RACH-less NTN handover, Xn signalling in detail |
-| Failure model | Qout/Qin with windows, N310/N311/T310, T304, command received during T310, re-establishment, link-monitoring restart | Qout/Qin as SINR thresholds (TR 36.839 values) instead of the BLER of a hypothetical PDCCH | BLER-based link monitoring; absolute failure rates are not calibrated: compare rules with each other |
+| Failure model | Qout/Qin with windows, N310/N311/T310, T304, command received during T310, re-establishment, link-monitoring restart | Qout/Qin as SINR thresholds (TR 36.839 values) instead of the BLER of a hypothetical PDCCH | BLER-based link monitoring; the absolute failure level: the ns-3 comparison setting passed the pre-registered checks on one fresh ns-3 set (TTT 80 and 320 ms) and failed the level on another (TTT 640 ms cells); the default gives a third to a sixth of ns-3's: compare rules with each other |
 | Time | 10 ms step by default (`protocol.step_s`); the effect of the step is measured in [time step](https://github.com/mjs19971997/handoverlab/blob/main/docs/time-step.md) | events rounded to the step | sub-slot timing |
 
 Built-in cards: `smoke`, `urban-grid-10ghz`, `fr3-urban-15ghz`, `urban-grid-28ghz-beams`, `dense-urban-2layer`,
@@ -268,9 +268,15 @@ The same 24 Event-A3 settings were simulated in HandoverLab and in the packet-le
 ns-3 with 5G-LENA. Handover and unnecessary-handover rates agree (median ratios 0.95 and 1.06,
 rank correlation 0.99; `handoverlab verify --ns3`, version 2.1.0). For failure rates, with the in-car loss of ns-3 and the restart of the link
 monitoring switched on, the order of settings and conditions agrees too, also on ns-3 results
-that were held back from any tuning (rank correlation 0.82-0.91). The absolute values
-differ, so compare failure rates between rules within HandoverLab. The causes are traced in
-[docs/calibration.md](https://github.com/mjs19971997/handoverlab/blob/main/docs/calibration.md). On two of them HandoverLab follows the 3GPP texts more closely
+that were held back from any tuning (rank correlation 0.82-0.91). For the failure level,
+the ns-3 comparison setting of 2.5.0 (`handoverlab.verify.ns3.COMPARISON_SETTING`: interferer load
+0.15 at link monitoring and ideal execution, with the in-car loss of ns-3;
+`handoverlab verify --ns3 --ns3-comparison`) passed the pre-registered checks on one fresh set of ns-3
+runs (V1, TTT 80 and 320 ms: level 0.97 of ns-3, rank 0.88) and failed the level on another (N3: 0.47,
+because of its TTT 640 ms cells). The default link-monitoring model gives a third to a sixth of ns-3's
+level (0.33 on V1, 0.16 on N3). The setting is not a default, so
+compare failure rates between rules within HandoverLab. The study and the causes of the differences are
+in [docs/calibration.md](https://github.com/mjs19971997/handoverlab/blob/main/docs/calibration.md). On two of the causes HandoverLab follows the 3GPP texts more closely
 than ns-3:
 
 - **In-car penetration loss.** TR 38.901 clause 7.4.3.2 gives it to a user inside a car. ns-3 adds
@@ -287,6 +293,16 @@ L1/L2-triggered mobility.
 
 ## What's new
 
+- **2.5.0**: an independent, pre-registered [validation study](https://github.com/mjs19971997/handoverlab/blob/main/docs/calibration.md#independent-validation-study-250). On 40
+  fresh ns-3 runs (V1, TTT 80 and 320 ms) the ns-3 comparison setting passed the pre-registered checks
+  (level 0.97, order 0.88); on the earlier fresh set N3 it failed the level (0.47, because of its TTT 640 ms
+  cells). It is now documented as code (`handoverlab.verify.ns3.COMPARISON_SETTING`,
+  `verify --ns3 --ns3-comparison`; not a default). Tuned on one card and tested on four unseen cards and
+  seeds, `a3_mro` and `dqn` kept fewer unnecessary handovers than tuned A3; `a3_bandit` met the criteria
+  only formally (more unnecessary handovers and ping-pong); `a3_pred` did not generalise. Limits of this
+  design: with 5 seeds the smallest two-sided Wilcoxon p is 0.0625, so the no-harm check could not fail, and
+  `fr3-urban-15ghz` is the training grid at another frequency, so it is the least independent test card
+  ([V2](https://github.com/mjs19971997/handoverlab/blob/main/docs/calibration.md#v2-do-the-adaptive-and-learning-rules-generalise)). No change of results.
 - **2.4.0**: UE receive beams (panels of TR 38.802, best beam or a sweep); a measurement-prediction rule after
   TR 38.744 (`a3_pred`: predicted Event A3 or measurement skipping, sample and hold or a trained ridge
   predictor); the slot scheduler as a compiled kernel (`run.backend: numba`, bit-identical; on the ns-3 card
@@ -511,9 +527,12 @@ the pages are plain Markdown in [docs/](https://github.com/mjs19971997/handoverl
     scheduler, the 7 GHz calibration and the comparison with other simulators.
 27. 2.4.1: pictures, citation and tutorials brought up to date; the example study
     completes again; no change of results.
-28. **2.4.2 (this release)**: every option has a picture; the dashboard pictures show the current version;
+28. 2.4.2: every option has a picture; the dashboard pictures show the current version;
     guide and tutorial examples rerun; facts made consistent; no change of results.
-29. Later (planned, not done), staying a handover simulator: the effect of a handover on what the user
+29. **2.5.0 (this release)**: an independent, pre-registered validation study: the ns-3 comparison setting
+    for the failure level (passed on one fresh set with TTT 80 and 320 ms, failed the level on N3), and the generalisation of the adaptive and learning rules to
+    unseen cards and seeds; no change of results.
+30. Later (planned, not done), staying a handover simulator: the effect of a handover on what the user
     sees (simple TCP and application models on top of the buffers), MIMO as an SINR gain, hundreds of
     users per run, and one scenario definition that also runs in ns-3; condEventT1 and earth-fixed beams.
 
@@ -523,9 +542,10 @@ If you use HandoverLab, please cite it as described in [CITATION.cff](https://gi
 it under *Cite this repository*). Every release is archived on Zenodo:
 [doi:10.5281/zenodo.23409131](https://doi.org/10.5281/zenodo.23409131) cites all versions (it resolves to
 the latest). To cite the exact version you used, take its DOI from the version list on that page, where
-the DOI of the latest version is listed; for example, version 2.4.1 is
+the DOI of the latest version is listed; for example, version 2.4.2 is
+[doi:10.5281/zenodo.23589215](https://doi.org/10.5281/zenodo.23589215), version 2.4.1
 [doi:10.5281/zenodo.23585308](https://doi.org/10.5281/zenodo.23585308) and version 2.4.0
-[doi:10.5281/zenodo.23582521](https://doi.org/10.5281/zenodo.23582521). The BibTeX entry below cites 2.4.1;
+[doi:10.5281/zenodo.23582521](https://doi.org/10.5281/zenodo.23582521). The BibTeX entry below cites 2.4.2;
 replace version and DOI with those of the version you used.
 
 ```bibtex
@@ -534,8 +554,8 @@ replace version and DOI with those of the version you used.
   title     = {{HandoverLab}: system-level handover simulator for 5G-Advanced and beyond-5G research},
   year      = {2026},
   publisher = {Zenodo},
-  version   = {2.4.1},
-  doi       = {10.5281/zenodo.23585308},
+  version   = {2.4.2},
+  doi       = {10.5281/zenodo.23589215},
   url       = {https://github.com/mjs19971997/handoverlab}
 }
 ```

{handoverlab-2.4.2 → handoverlab-2.5.0}/docs/calibration.md

@@ -4,6 +4,14 @@ The radio model itself is calibrated against 3GPP (TR 38.901 clause 7.8.1, the 2
 R1-165974); see [radio calibration against 3GPP](calibration-3gpp.md). This page is about the
 failure model, which no 3GPP calibration covers.
 
+**Where the failure level stands (2.5.0).** The *ns-3 comparison setting*
+(`handoverlab.verify.ns3.COMPARISON_SETTING`: interferer load 0.15 at link monitoring, ideal execution,
+with the in-car loss of ns-3) passed the pre-registered checks against ns-3 / 5G-LENA on one fresh set
+of ns-3 runs (V1, TTT 80 and 320 ms: level 0.97, rank 0.88) and failed the level on another (N3: 0.47,
+because of its TTT 640 ms cells). The default link-monitoring model gives a third to a sixth of ns-3's
+level (0.33 on V1, 0.16 on N3). The setting is not a default. See the [independent validation study (2.5.0)](#independent-validation-study-250) at the
+end of this page, which also tests whether the adaptive and learning rules generalise.
+
 **Fresh hold-out D (1.9.0).** 48 new ns-3 runs on conditions never used before (12 and 20 m/s)
 were compared with the 1.3.0 configuration fixed in advance: handover and unnecessary-handover
 rates agree (median ratios 0.93 and 0.95, ranks 0.97), and the failure level agrees too (ratio
@@ -53,7 +61,9 @@ traffic), with limits fixed before the runs:
 At TTT 100 ms the fixed load gives ns-3's failure counts (17 against 14, 11 against 10); at
 TTT 640 ms it gives about half of them (84 against 180, 68 against 193), the known effect of ns-3's
 slow out-of-sync detection (below). As fixed in advance, the setting is not adopted because the
-level check fails; it is reported here, and no further tuning was done on these runs.
+level check fails; it is reported here, and no further tuning was done on these runs. It was
+adopted as the comparison setting in 2.5.0 after V1, see
+[below](#independent-validation-study-250).
 
 **Summary (1.5.0).** Handover and unnecessary-handover rates of HandoverLab agree with ns-3 /
 5G-LENA. For failure rates, the order of settings and conditions agrees on part A and on both
@@ -381,3 +391,111 @@ time should follow the control traffic of each cell.
 
 Reproduce with `compare(seeds=[500, 501], overrides=...)` and
 `holdout(seeds=[500, 501, 502, 503], overrides=...)` from `handoverlab.verify.ns3`.
+
+## Independent validation study (2.5.0)
+
+A study in two parts was registered on 2026-10-24, before any of its runs, with its conditions, seeds,
+criteria and decisions fixed; one amendment (2026-10-25, before any run of part V2) fixed the tuning
+grids and the test procedure without changing a criterion, card, seed or selection rule. Nothing was
+tuned on the study's data, and every result is reported as it came. Code: HandoverLab 2.4.2 (results
+identical to 2.4.0).
+
+### V1: failure rate against fresh ns-3 runs
+
+**Runs.** 40 new ns-3 / 5G-LENA runs (`benchmarks/ns3/handoverlab-ns3-a3.cc`, ns-3.48 with the
+documented upstream commits, 5G-LENA v5.1 with the one documented local change, see
+`benchmarks/ns3/README.md`) on conditions never used before: urban, 20 users, 180 s (60 s
+discarded), light traffic, A3 3 dB, site distance 200 and 300 m, 10 and 28 m/s (both inside the
+30-120 km/h range of the ns-3 in-car loss), time-to-trigger 80 and 320 ms, seeds 401-405: 8 cells of
+5 runs. HandoverLab ran `verify.ns3.scenario_for(isd, v, car=True)` with seeds 401-405 in two rows
+fixed in advance:
+
+- **R** (reference): the 2.4.2 defaults with `protocol.exec_can_fail: false` (ns-3 has ideal execution);
+- **C** (the N3 candidate above, not re-tuned): R with `protocol.lm_load: 0.15`.
+
+| Row | F1 level, sum HandoverLab / sum ns-3 (0.67-1.5) | F2 order, Spearman over the 8 cells (at least 0.8) | F3 handover rate, median ratio (0.8-1.25) | F4 TTT direction (3 of 4) |
+|---|---|---|---|---|
+| C: `lm_load` 0.15, ideal execution | 0.97, passes | 0.88, passes | 0.965, passes | 4, passes |
+| R: 2.4.2 link monitoring, ideal execution | 0.33, fails | 0.84, passes | 0.973, passes | 4, passes |
+
+Failures summed over the 5 seeds per cell (site distance / speed / time-to-trigger):
+
+| Cell | 200 m, 10 m/s, 80 ms | 200, 10, 320 | 200, 28, 80 | 200, 28, 320 | 300, 10, 80 | 300, 10, 320 | 300, 28, 80 | 300, 28, 320 | Total |
+|---|---|---|---|---|---|---|---|---|---|
+| ns-3 | 16 | 29 | 7 | 47 | 3 | 15 | 4 | 12 | 133 |
+| HandoverLab, row C | 8 | 46 | 7 | 33 | 5 | 16 | 3 | 11 | 129 |
+| HandoverLab, row R | 6 | 12 | 2 | 13 | 3 | 6 | 0 | 2 | 44 |
+
+**Decision, as registered.** Row C passes F1-F3 on V1, the fresh set after N3 (on which it had failed F1), so it is the
+documented **ns-3 comparison setting** of 2.5.0: `handoverlab.verify.ns3.COMPARISON_SETTING`
+(`{"protocol.lm_load": 0.15, "protocol.exec_can_fail": False}`), used with the in-car loss of ns-3
+(`scenario_for(isd, v, car=True, comparison=True)`, `compare(..., car=True, comparison=True)`, or
+`handoverlab verify --ns3 --ns3-comparison`, which adds the in-car loss itself). It is not a default:
+every default, golden fingerprint and stored result is unchanged.
+
+**Validity range.** The setting passed the pre-registered checks on one fresh set only (V1,
+time-to-trigger 80 and 320 ms). On N3 the same row failed the level (0.47) because of the TTT 640 ms
+cells, where it gives about half of ns-3's failures (84 against 180, 68 against 193, 30 against 46,
+36 against 80), the slow out-of-sync detection of ns-3 described in the version 1.4.0 section; its
+TTT 100 ms cells matched (17 against 14, 11 against 10, 1 against 3, 3 against 1), but matching at
+100 ms was not a registered criterion. Both results stand side by side. The default link-monitoring
+model (row R) gives a third to a sixth of ns-3's failure level (0.33 here, 0.16 on N3), with the order
+of the cells kept here (0.84) but not on N3 (0.78).
+
+A run of 5G-LENA without the local change is not part of V1: it aborts the run instead of producing
+data, and how often it would do so cannot be measured in the optimised build (logging compiled out).
+
+### V2: do the adaptive and learning rules generalise?
+
+**Design.** Rules `a3_mro`, `a3_bandit`, `a3_pred` (ridge predictor, case A) and `dqn`, against
+A3-ref (3 dB, 160 ms) and A3-tuned. Tuning and training on `urban-grid-10ghz`, seeds 101-104 only:
+8 evaluated settings per rule from its grid (5 drawn at random, 3 around the best), the lowest
+`unnecessary_pm` among settings with `failures_pm` at most that of A3-ref on the same runs (budget
+0.0638 per UE-minute), ties within 5 % broken by fewer RRC messages. Settings and weights were frozen
+before any test run. Test cards never used for tuning: `ns3-urban-3.5ghz`, `urban-macro-tr37885-4ghz`,
+`highway-tr37885-4ghz`, `fr3-urban-15ghz`, with test seeds 501-505 and each card's default length and
+users; also the training card with the test seeds. Criteria, paired by card and seed against
+A3-tuned (two-sided Wilcoxon, Holm over the 4 test cards):
+
+- **G-A (no harm):** failures not significantly higher than A3-tuned's on at least 3 of the 4 test cards;
+- **G-B (gain kept):** the sign of the mean difference in `unnecessary_pm` on the training card's test
+  seeds is the same on at least 3 of the 4 test cards;
+- cost flags, no limit: attempts, ping-pong or RRC messages above 1.5 times A3-tuned's on a test card.
+
+A rule generalises if it passes G-A and G-B.
+
+**Selected settings.** A3-tuned 4 dB / 160 ms; `a3_mro` offset 6 dB, 160 ms, step 2 dB, window 5 s;
+`a3_bandit` arms 1-5 dB, 40 ms, epoch 5, `w_failure` 2; `a3_pred` offset 6 dB, 80 ms, prediction window
+0.4 s; `dqn` offsets 0-6 dB, 160 ms, `w_failure` 1.
+
+Difference to A3-tuned in unnecessary handovers per UE-minute (rule minus A3-tuned, mean over seeds
+501-505):
+
+| Rule | `urban-grid-10ghz` (training card) | `ns3-urban-3.5ghz` | `urban-macro-tr37885-4ghz` | `highway-tr37885-4ghz` | `fr3-urban-15ghz` | G-A | G-B | Verdict |
+|---|---|---|---|---|---|---|---|---|
+| `a3_mro` | -0.780 | -1.120 | -4.793 | -0.637 | -0.798 | 4 of 4 | 4 of 4 | generalises |
+| `dqn` | -0.357 | -0.520 | -1.408 | -0.382 | -0.363 | 4 of 4 | 4 of 4 | generalises |
+| `a3_bandit` | +1.644 | +0.033 | +4.069 | +0.537 | +1.617 | 4 of 4 | 4 of 4 | meets the criteria, but worse (below) |
+| `a3_pred` | -0.288 | not run | +0.946 | -0.507 | -0.312 | 3 of 4 | 2 of 4 | does not generalise |
+
+- **`a3_mro` and `dqn` generalise.** Both keep fewer unnecessary handovers than A3-tuned on all four
+  test cards (every seed in the same direction; Wilcoxon p 0.0625, Holm 0.25), with no cost flag. Their
+  failure differences are small and of both signs (`a3_mro` -0.307 on `urban-macro-tr37885-4ghz`,
+  +0.021 on `fr3-urban-15ghz`; `dqn` +0.020 and +0.015 per UE-minute), none significant.
+- **`a3_bandit` is worse in unnecessary handovers and ping-pong, although it formally meets the
+  registered criteria.** G-B checks only that the sign stays the same, and its sign is +: the setting
+  chosen within the failure budget already had more unnecessary handovers than A3-tuned on the training
+  card (+1.644 per UE-minute), and that loss stays on every test card. It has fewer failures (0.782
+  against 1.759 per UE-minute on `urban-macro-tr37885-4ghz`) and pays with 1.65, 4.15 and 2.80 times
+  A3-tuned's ping-pong on `urban-macro-tr37885-4ghz`, `highway-tr37885-4ghz` and `fr3-urban-15ghz`.
+  Its G-B pass is a consistent loss, not a kept gain.
+- **`a3_pred` does not generalise.** It loses the sign on `urban-macro-tr37885-4ghz` (+0.946
+  unnecessary handovers per UE-minute, while failures fall from 1.759 to 0.384), and it cannot run on
+  `ns3-urban-3.5ghz`: that card measures every 0.2 s, the predictor was trained at the 0.04 s of the
+  training card, and the rule refuses a predictor trained with another measurement period (counted as
+  not passed, as registered).
+
+**Limits of the design.** With 5 paired seeds the smallest two-sided exact Wilcoxon p is 0.0625, so no
+card can show significant harm and G-A cannot fail; read the failure differences themselves.
+`fr3-urban-15ghz` has the same street grid and users as the training card on another carrier and gives
+nearly the same numbers, so it is the least independent of the four test cards.

{handoverlab-2.4.2 → handoverlab-2.5.0}/docs/comparison.md

@@ -1,6 +1,6 @@
 # Comparison with other simulators
 
-This page sets HandoverLab 2.4.0 next to other open or widely used 5G simulators and emulators, on the points
+This page sets HandoverLab 2.5.0 next to other open or widely used 5G simulators and emulators, on the points
 that matter for handover and mobility studies. It is meant to help you pick the right tool for a question, not
 to rank tools: most of them were built for other questions, and several are far more detailed than HandoverLab
 in layers that HandoverLab abstracts.
@@ -9,13 +9,13 @@ in layers that HandoverLab abstracts.
 repository (README, docs, source tree, release notes) or its peer-reviewed paper; the source labels in brackets
 point to the [list of sources](#sources), all accessed on 2026-10-22. **"not stated"** means the fact was not found
 in those sources; it does not prove that the feature is absent, and a later release may add it. Corrections are
-welcome as issues. The HandoverLab column follows the code and the pages of this site for version 2.4.0.
+welcome as issues. The HandoverLab column follows the code and the pages of this site for version 2.5.0.
 
 Tools compared (latest release found on 2026-10-22):
 
 | Tool | Kind | Latest release | Licence | Language |
 |---|---|---|---|---|
-| HandoverLab | system-level, procedure-centred, time-stepped | 2.4.0 (2026-10-22) | MIT | Python (optional Numba kernel) |
+| HandoverLab | system-level, procedure-centred, time-stepped | 2.5.0 (2026-10-25) | MIT | Python (optional Numba kernel) |
 | ns-3 with 5G-LENA (`nr` module) | packet-level, end-to-end, discrete-event | v5.1 (2026-08-06, ns-3.48) [L5] | GPLv2 [L6] | C++ [L6] |
 | ns-3 mmWave module (NYU / UniPD) | packet-level, end-to-end, discrete-event | v8.0 (2024-06-26, ns-3.42) [M2] | GPL-2.0 [M1] | C++ [M1] |
 | Simu5G (OMNeT++ / INET) | packet-level, end-to-end, discrete-event; real-time emulation | 1.8.0 (2026-10-07) [S2] | LGPL-3.0 [S7] | C++ and NED [S1] |
@@ -28,7 +28,7 @@ Tools compared (latest release found on 2026-10-22):
 
 | Tool | Event A3 / RRC handover | CHO | DAPS | LTM | Radio-link failure | Dual connectivity |
 |---|---|---|---|---|---|---|
-| HandoverLab 2.4.0 | yes: report, preparation, command, execution; A5 between carriers; a rule on predicted measurements after TR 38.744 ([AI/ML mobility](guides/ai-mobility.md)) | yes (Rel-16, up to 8 candidates; D1/D2 for NTN) | yes | yes, and conditional LTM | Qout/Qin as SINR thresholds with windows (or the MIESM effective SINR of the hypothetical PDCCH with fading), N310/N311/T310, T304, command during T310, re-establishment after a fixed outage; absolute failure rates are not calibrated | NR-DC as an option: SN addition, PSCell change, SN release, SCG failure; no EN-DC |
+| HandoverLab 2.5.0 | yes: report, preparation, command, execution; A5 between carriers; a rule on predicted measurements after TR 38.744 ([AI/ML mobility](guides/ai-mobility.md)) | yes (Rel-16, up to 8 candidates; D1/D2 for NTN) | yes | yes, and conditional LTM | Qout/Qin as SINR thresholds with windows (or the MIESM effective SINR of the hypothetical PDCCH with fading), N310/N311/T310, T304, command during T310, re-establishment after a fixed outage; absolute failure rates are not calibrated | NR-DC as an option: SN addition, PSCell change, SN release, SCG failure; no EN-DC |
 | ns-3 5G-LENA v5.1 | yes: X2-based, intra- and inter-frequency, A3 and A2-A4 algorithms, CIO; TTT scaling and ping-pong guards in v5.1 [L2, L3, L5] | not stated | not stated | not stated | Qout/Qin from the hypothetical-PDCCH BLER, N310/N311/T310, re-establishment; optional TR 36.839 handover-failure model (v5.1) [L2, L4, L5] | no: "out of scope and is future work" [L3] |
 | ns-3 mmWave v8.0 | mmWave secondary-cell switch coordinated by the LTE eNB (SINR difference with fixed or dynamic TTT), not an A3 configuration as such [M1, M4, M5] | not stated | not stated | not stated | mmWave outage by an SINR threshold; T310/N310: not stated [M4] | LTE-mmWave DC (LTE master, mmWave secondary) [M1, M5]; NR-DC: not stated |
 | Simu5G 1.8.0 | yes: Xn-prepared handover on a measurement report with the best cell, hysteresis on RSSI; A3 with TTT: not stated [S3, S4] | not stated | not stated | not stated | RLF when an RLC AM PDU exceeds its retransmission limit, RRC re-establishment (T311 = 0 disables it by default); T310/N310: not stated [S2] | EN-DC and NE-DC with split bearers [S1, S6]; NR-DC: not stated |
@@ -41,7 +41,7 @@ Tools compared (latest release found on 2026-10-22):
 
 | Tool | NTN | Beams | Fast fading and link-to-system mapping | Scheduler |
 |---|---|---|---|---|
-| HandoverLab 2.4.0 | one LEO satellite with earth-moving beams (TR 38.811, TR 38.821), CHO with D2; no several satellites, Doppler or earth-fixed beams ([NTN guide](guides/ntn.md)) | SSB beams per sector from the TR 38.901 element and DFT beams, cell quality from beams, beam failure detection and recovery; UE receive beams optional (1, 2 or 4 panels, [UE beams](guides/ue-beams.md)), isotropic UE by default; no MIMO ([beams](guides/beams-layers.md)) | off by default (large-scale channel with a slow time-varying part); option: TDL-A to TDL-E with MIESM for link monitoring and a capacity-equivalent SINR for the rate; no CDL ([fading](guides/fading.md)) | by default a rate model without a scheduler; option: slot scheduler RR or PF with MCS, TBS and HARQ (base engine only; with `run.backend: numba` bit-identical and, on the ns-3 card, 42 (`rr`) and 93 (`pf`) times faster than its NumPy loop) ([scheduler](guides/scheduler.md)) |
+| HandoverLab 2.5.0 | one LEO satellite with earth-moving beams (TR 38.811, TR 38.821), CHO with D2; no several satellites, Doppler or earth-fixed beams ([NTN guide](guides/ntn.md)) | SSB beams per sector from the TR 38.901 element and DFT beams, cell quality from beams, beam failure detection and recovery; UE receive beams optional (1, 2 or 4 panels, [UE beams](guides/ue-beams.md)), isotropic UE by default; no MIMO ([beams](guides/beams-layers.md)) | off by default (large-scale channel with a slow time-varying part); option: TDL-A to TDL-E with MIESM for link monitoring and a capacity-equivalent SINR for the rate; no CDL ([fading](guides/fading.md)) | by default a rate model without a scheduler; option: slot scheduler RR or PF with MCS, TBS and HARQ (base engine only; with `run.backend: numba` bit-identical and, on the ns-3 card, 42 (`rr`) and 93 (`pf`) times faster than its NumPy loop) ([scheduler](guides/scheduler.md)) |
 | ns-3 5G-LENA v5.1 | NTN channel (TR 38.811, from ns-3 mainline [L9]) and a LEO mobility example [L1, L2] | ideal and SRS-based realistic beamforming; beam management "Simplified model; no SSB blocks" [L1]; quasi-omni beams in the RRC / handover context [L3] | TR 38.901 with fast fading; EESM-based PHY abstraction with SINR-BLER tables [L1, L8] | PF, RR, MR, QoS-aware, RL-based; OFDMA and TDMA [L1] |
 | ns-3 mmWave v8.0 | TR 38.811 channel inherited from ns-3.42; no NTN protocol features stated [M2] | SVD- and DFT-based beamforming; NR beam tracking listed as future work [M1, M3] | TR 38.901 channel, ray-tracing and measured traces; EESM error model from 5G-LENA [M1, M3] | flexible-TTI RR, PF, max-rate, max-weight [M1] |
 | Simu5G 1.8.0 | not in the official release; separate third-party work exists [S10] | not stated; antenna-gain link budget only [S1] | path loss, LOS and shadowing of TR 36.814 / 36.873 / 38.901 with Jakes or Rayleigh fading; reception from SINR and BLER curves [S5, S6] | MAX C/I, PF, DRR, QoS-aware PF [S1] |
@@ -54,7 +54,7 @@ Tools compared (latest release found on 2026-10-22):
 
 | Tool | Speed and scale | Validation against 3GPP |
 |---|---|---|
-| HandoverLab 2.4.0 | one process: 2 rules, 40 users, 76 cells, 60 s simulated in 10-15 s on a modest virtual machine (1.11.0 timings, [performance](performance.md)); many rules share one world; no published figures for thousands of nodes | large-scale calibration of TR 38.901 clause 7.8.1 against the 21 companies of R1-165974 (325 of 342 percentiles inside the range) and against R1-2506406 (at 7 GHz all 228 percentiles of UMa, UMi and SMa inside the company range, largest distance from the company mean 1.69-2.43 dB; with the two 6 GHz reruns 342 percentiles, 1.65-2.88 dB, [details](calibration-3gpp.md)); handover counts against ns-3 / 5G-LENA; failure levels differ from ns-3 ([calibration](calibration.md)); clause-by-clause [standard compliance](standard-compliance.md) |
+| HandoverLab 2.5.0 | one process: 2 rules, 40 users, 76 cells, 60 s simulated in 10-15 s on a modest virtual machine (1.11.0 timings, [performance](performance.md)); many rules share one world; no published figures for thousands of nodes | large-scale calibration of TR 38.901 clause 7.8.1 against the 21 companies of R1-165974 (325 of 342 percentiles inside the range) and against R1-2506406 (at 7 GHz all 228 percentiles of UMa, UMi and SMa inside the company range, largest distance from the company mean 1.69-2.43 dB; with the two 6 GHz reruns 342 percentiles, 1.65-2.88 dB, [details](calibration-3gpp.md)); handover counts against ns-3 / 5G-LENA; failure level: the defaults give a third to a sixth of ns-3's, the comparison setting passed one fresh pre-registered set (TTT 80 and 320 ms) and failed another (TTT 640 ms) ([calibration](calibration.md)); clause-by-clause [standard compliance](standard-compliance.md) |
 | ns-3 5G-LENA v5.1 | runtime numbers: not stated for the module; a MIMO channel speed-up of up to 16 times is reported in a WNS3 paper [L11]; the calibration scenario has 12 gNBs and 120 UEs [L10] | calibrated in 3GPP outdoor reference scenarios (SIMPAT 2022) [L7]; calibration examples for RP-180524 [L2]; mobility checked against TR 36.839 (v5.1) [L5] |
 | ns-3 mmWave v8.0 | not stated | not stated (examples "verify its correct functioning" [M6]) |
 | Simu5G 1.8.0 | background cells and UEs for large scenarios; real-time emulation of "hundreds of simulated users and tens of cells" on one desktop [S1, S9] | PHY abstraction validated in 3GPP-based scenarios [S8]; fingerprint regression tests [S1] |
@@ -77,8 +77,8 @@ Tools compared (latest release found on 2026-10-22):
 - **Scale.** The Vienna simulator reports thousands of nodes [V1]; Simu5G emulates tens of cells in real time
   [S9]. HandoverLab runs in one Python process per world and is sized for tens of cells and users per run.
 - **Packet-level handover against the 3GPP mobility study.** 5G-LENA v5.1 can be checked against the TR 36.839
-  handover-failure curves [L5], which matters because HandoverLab's absolute failure rates are not calibrated
-  ([calibration](calibration.md)).
+  handover-failure curves [L5], which matters because HandoverLab's absolute failure level is checked against ns-3 / 5G-LENA only: the ns-3 comparison setting (`handoverlab.verify.ns3.COMPARISON_SETTING`, with the in-car loss of ns-3) passed the pre-registered checks on one fresh set of ns-3 runs (V1, TTT 80 and 320 ms: level 0.97, rank 0.88) and failed the level on another (N3: 0.47, because of its TTT 640 ms cells); the default link-monitoring model gives a third to a sixth of ns-3's level (0.33 on V1, 0.16 on N3)
+  ([calibration](calibration.md#independent-validation-study-250)).
 
 ## Where HandoverLab differs
 
@@ -95,7 +95,7 @@ Tools compared (latest release found on 2026-10-22):
 
 All accessed on 2026-10-22.
 
-**HandoverLab:** the pages linked above and `CHANGELOG.md` of 2.4.0.
+**HandoverLab:** the pages linked above and `CHANGELOG.md` of 2.5.0.
 
 **ns-3 5G-LENA**
 

{handoverlab-2.4.2 → handoverlab-2.5.0}/docs/guides/ai-mobility.md

@@ -162,6 +162,15 @@ almost all of the gain comes from not waiting for the time-to-trigger: sample an
 passed only by 0.0002 attempts per UE per second), and both make 55 % more attempts and three times the
 ping-pongs. The TR tables report no ping-pong rate; read the gain together with that cost.
 
+**Generalisation (2.5.0).** Tuned and trained on `urban-grid-10ghz` (ridge, case A) and tested on four other
+cards with unseen seeds in a pre-registered study ([V2](../calibration.md#v2-do-the-adaptive-and-learning-rules-generalise)), `a3_pred` did not generalise: on
+`urban-macro-tr37885-4ghz` it had more unnecessary handovers than tuned A3 (+0.95 per UE-minute) while its
+failures fell (0.38 against 1.76), and it cannot run on `ns3-urban-3.5ghz`, whose 0.2 s measurement period
+differs from the 0.04 s the predictor was trained at (the rule refuses such a predictor). Limits of the design:
+with 5 seeds the smallest two-sided Wilcoxon p is 0.0625, so the no-harm check could not fail, and
+`fr3-urban-15ghz` is the training grid at another frequency, so it is the least independent test card
+([V2](../calibration.md#v2-do-the-adaptive-and-learning-rules-generalise)).
+
 The runner and the full numbers are kept outside the package; `handoverlab verify --only learning` repeats a
 short check of the mechanics (P1-P4) on the `smoke` card.
 

{handoverlab-2.4.2 → handoverlab-2.5.0}/docs/guides/indoor-rural.md

@@ -92,8 +92,12 @@ Means over three seeds per user-minute, with the cards as they are and with the
   about 15 dB (InH at 20 m) when its state changes. In rural cells these jumps raise the failures from
   0.07 to 0.18 per user-minute and the handovers by about a fifth (13.07 to 15.62); indoors there are
   no failures with either state, and the hard switch adds only a few handovers (3.81 to 3.95).
-- The failure model is not calibrated in absolute terms in any scenario; read failure rates
-  relative to each other.
+- The absolute failure level was checked against ns-3 only on `ns3-urban-3.5ghz`, with the ns-3
+  comparison setting (it passed on one fresh set with TTT 80 and 320 ms and failed the level on another
+  with TTT 640 ms cells; [calibration](../calibration.md#independent-validation-study-250)), not in these
+  scenarios; the default link-monitoring model gives a third to a sixth of ns-3's level (0.33 on V1, 0.16
+  on N3). Read
+  failure rates relative to each other.
 
 ## 4. Change them