handoverlab 2.4.2__tar.gz → 2.6.0__tar.gz

handoverlab-2.6.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.6.0}/CHANGELOG.md

@@ -7,6 +7,134 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [2.6.0] - 2026-10-25
+
+No change of defaults or results: every golden fingerprint is unchanged. This release corrects a wrong
+claim of 2.5.0 about the failure level (see "Corrected").
+
+### Added
+
+- A bridge to ns-3 / 5G-LENA (`handoverlab.ns3bridge`, `handoverlab ns3 export|import|compare`;
+  [guide](docs/guides/ns3-bridge.md)). An ns-3 study file (`examples/ns3_study_v1.yaml`) defines conditions
+  (site distance, speed, time-to-trigger, A3 offset, traffic, fading), users, run length and seeds once.
+  `export` writes a ready-to-run package of the program `benchmarks/ns3/handoverlab-ns3-a3.cc`: the program,
+  `build.sh`, `run.py` (standard library only, resumable, parallel, zips the results), `run.ps1` and
+  `manifest.json` (study hash, HandoverLab version, every ns-3 command line). `import` reads the run JSONs
+  into a reference file in the format of `handoverlab.verify.ns3.load_reference`. `compare` runs HandoverLab
+  on the same cells and seeds (ideal execution, the in-car loss of ns-3; `--comparison` adds the comparison
+  setting of 2.5.0) and applies the checks of the studies N3 and V1 (F1 level, F2 order, F3 handover rate,
+  F4 time-to-trigger effect) with the limits as options. Options the program cannot simulate (other cards,
+  beams, NTN, CHO, DAPS, LTM, other site distances, unknown keys) are refused, naming the option, before any
+  file is written.
+- `handoverlab.ns3bridge` is part of the public surface (`tests/data/public_api.json`).
+
+### Validation
+
+- Pre-registered acceptance of the bridge: exporting the V1 design gives the program options of the hand-made
+  V1 package run by run (40 command lines); importing the 40 V1 results and running `compare` with and
+  without the comparison setting gives the numbers of V1 (rows C and R) exactly, with
+  `handoverlab.run_length: card`, the HandoverLab run length registered for V1 (150 s with 60 s warm-up, so
+  90 s measured against 120 s in ns-3). With the same run length on both sides (`run_length: study`, the
+  default; not registered) the comparison setting gives level 1.31, rank correlation 0.62 (below the limit
+  0.8), handover-rate ratio 0.92 and the TTT sign in 4 of 4 pairs; the default link monitoring 0.32, 0.62,
+  0.94 and 4 of 4. This difference revealed the error corrected below.
+
+### Corrected
+
+- **The failure-level analyses of 2.5.0 compared unequal run lengths.** For the fresh ns-3 sets N3, V1 and
+  V3 the HandoverLab side ran the card's 150 s with 60 s warm-up (90 s measured), while ns-3 ran 180 s with
+  60 s discarded (120 s measured); the level (F1) and order (F2) checks compare failure counts summed over
+  the cells, so the HandoverLab counts covered three quarters of the ns-3 time. A corrected analysis was
+  registered (amendment E1) before any corrected result was seen and applied to all three sets: equal run
+  lengths (180 s, 60 s discarded on both sides), same ns-3 runs, seeds, rows and criteria.
+- Corrected results (registered analysis with the wrong run length in brackets). The ns-3 comparison
+  setting: N3 level 0.52 (0.47), fails; V1 level 1.31 (0.97) but rank correlation 0.62 (0.88), fails; V3
+  level 0.64 (0.44), fails. So it passes F1-F3 on none of the three sets. The defaults (default link
+  monitoring, ideal execution) fail level and rank on all three: level 0.18 / 0.32 / 0.17 (0.16 / 0.33 /
+  0.095), rank 0.71 / 0.62 / 0.76. The handover-rate ratio (0.86-0.96) and the direction of the
+  time-to-trigger effect pass in every set and row. A rate-based level (failures per UE-minute, not affected
+  by the run length) equals the corrected count-based level in every set and row.
+- Consequence: the 2.5.0 statement that the comparison setting passed the pre-registered checks on V1 is
+  withdrawn. The absolute failure level is **not calibrated**: the comparison setting gives 0.5-1.3 times
+  ns-3's failure level depending on the set, and its order of failures across cells is not
+  reliable. `COMPARISON_SETTING`, `comparison=True` and `verify --ns3-comparison` are kept (the stability
+  policy keeps them within 2.x) and documented as a setting that brings the level closer, not validated.
+- Not affected: the comparisons of handover and unnecessary-handover rates (part A of the stored ns-3
+  reference, `handoverlab verify --ns3`, `verify.ns3.compare`) and N2, which use rates per UE-minute.
+- V3 (registered 2026-10-25 before its runs: 40 fresh ns-3 runs, site distance 200 / 300 m, 10 / 28 m/s,
+  time-to-trigger 512 / 1024 ms, seeds 601-605, 1122 ns-3 failures): the comparison setting fails the level
+  in both analyses (0.44 registered, 0.64 corrected) with rank 0.87 / 0.88; the defaults 0.095 / 0.17. At
+  long time-to-trigger HandoverLab has fewer failures than ns-3, consistent with ns-3's slower out-of-sync
+  detection (0.65-0.83 s), which HandoverLab does not model.
+- Planned, not in this release: an "ns-3-like" option (not a default) that imitates ns-3's slower
+  out-of-sync detection, built from the ns-3 data already seen and judged on a fresh set V4 (site distance
+  200 / 400 m, 14 / 22 m/s, time-to-trigger 128 / 1280 ms, seeds 701-705), collected and kept unopened until
+  the option and its settings are frozen.
+- Corrected everywhere the 2.5.0 claim appeared: README ("Checked against ns-3", the boundary table, What's
+  new), `docs/calibration.md` (the summary and the 2.5.0 study, with the registered numbers kept next to the
+  corrected ones, and new sections on V3 and the correction), `docs/comparison.md`, `docs/verification.md`,
+  `docs/standard-compliance.md`, the user guide, the guides, the 12 scenario cards (scenario pages
+  regenerated), the docstrings of `handoverlab.verify.ns3`, the note of `verify --ns3 --ns3-comparison`, and
+  the help of `verify --ns3-comparison` and `ns3 compare --comparison` (command-line reference regenerated).
+
+### Documentation
+
+- Version 2.6.0 in the README, the user guide, the documentation home page and the citation metadata.
+  Dashboard screenshots retaken with this version.
+
+## [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 (corrected in 2.6.0: with equal run lengths it fails the rank on V1, 0.62, and is not validated).
+  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) (withdrawn in 2.6.0: wrong run length; see Corrected)
+  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) (corrected
+  in 2.6.0). 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 +1248,9 @@ 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.6.0...HEAD
+[2.6.0]: https://github.com/mjs19971997/handoverlab/compare/v2.5.0...v2.6.0
+[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.6.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.6.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.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: handoverlab
-Version: 2.4.2
+Version: 2.6.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.6.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 is not calibrated: with equal run lengths the default gives 0.17-0.32 of ns-3's and the ns-3 comparison setting 0.5-1.3 depending on the set, passing the pre-registered checks on none of three fresh ns-3 sets (corrected in 2.6.0): 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,19 @@ 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). **The absolute failure level is not
+calibrated.** On three fresh, pre-registered sets of ns-3 runs (N3, V1, V3), compared over equal run
+lengths, the default link-monitoring model gives 0.18, 0.32 and 0.17 of ns-3's failure level and fails
+level and order on all three. 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`) brings the level closer but is
+not validated: 0.52 (N3), 1.31 (V1, where the order of failures across cells fails, rank 0.62) and 0.64
+(V3), so 0.5-1.3 times ns-3's level depending on the set, passing the checks on none of the
+three sets. The handover-rate ratio (0.86-0.96) and the direction of the time-to-trigger effect agree in
+every set. *Corrected in 2.6.0:* 2.5.0 reported that the setting passed on V1 (level 0.97, rank 0.88);
+that analysis compared 90 s of HandoverLab with 120 s of ns-3. 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
@@ -343,8 +353,28 @@ HandoverLab has had this as an option since 1.3.0 (`protocol.rlm_holdoff_s`), on
 covers baseline handover at 3.5 GHz only: 5G-LENA has no conditional handover, DAPS or
 L1/L2-triggered mobility.
 
+To run your own study in both simulators, `handoverlab ns3 export|import|compare` writes the ns-3 package, reads its results back and applies the same checks ([guide](https://github.com/mjs19971997/handoverlab/blob/main/docs/guides/ns3-bridge.md)).
+
 ## What's new
 
+- **2.6.0**: a bridge to ns-3 / 5G-LENA (`handoverlab ns3 export|import|compare`) that writes a ready-to-run
+  ns-3 package for a study, reads its results back and applies the checks of the ns-3 studies
+  ([guide](https://github.com/mjs19971997/handoverlab/blob/main/docs/guides/ns3-bridge.md)). It found an error in 2.5.0: the failure counts of
+  HandoverLab covered 90 s against 120 s of ns-3. Corrected, the ns-3 comparison setting passes the
+  pre-registered checks on none of the three fresh ns-3 sets (level 0.52, 1.31 with rank 0.62, 0.64): the
+  absolute failure level is not calibrated ([correction](https://github.com/mjs19971997/handoverlab/blob/main/docs/calibration.md#correction-in-260-equal-run-lengths)). Handover-rate comparisons were not
+  affected. No change of results.
+- **2.5.0** (corrected in 2.6.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 was reported to pass the
+  pre-registered checks (level 0.97, order 0.88); this compared 90 s of HandoverLab with 120 s of ns-3, and
+  with equal run lengths it fails the order on V1 (rank 0.62) and the level on N3 and V3 (0.52, 0.64), so it
+  is not validated. It is 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 +599,16 @@ 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: an independent, pre-registered validation study: the ns-3 comparison setting for the
+    failure level (its pass on V1 was corrected in 2.6.0: not validated), and the generalisation of the
+    adaptive and learning rules to unseen cards and seeds; no change of results.
+30. **2.6.0 (this release)**: the bridge to ns-3 / 5G-LENA (export, import, compare); the correction of the
+    2.5.0 failure-level comparison (equal run lengths: the absolute failure level is not calibrated); no
+    change of results.
+31. Later (planned, not done), staying a handover simulator: an "ns-3-like" option imitating ns-3's slower
+    out-of-sync detection, judged on a fresh ns-3 set (V4) kept unopened until it is frozen; 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 +618,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 +630,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.6.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.6.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 is not calibrated: with equal run lengths the default gives 0.17-0.32 of ns-3's and the ns-3 comparison setting 0.5-1.3 depending on the set, passing the pre-registered checks on none of three fresh ns-3 sets (corrected in 2.6.0): 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,19 @@ 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). **The absolute failure level is not
+calibrated.** On three fresh, pre-registered sets of ns-3 runs (N3, V1, V3), compared over equal run
+lengths, the default link-monitoring model gives 0.18, 0.32 and 0.17 of ns-3's failure level and fails
+level and order on all three. 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`) brings the level closer but is
+not validated: 0.52 (N3), 1.31 (V1, where the order of failures across cells fails, rank 0.62) and 0.64
+(V3), so 0.5-1.3 times ns-3's level depending on the set, passing the checks on none of the
+three sets. The handover-rate ratio (0.86-0.96) and the direction of the time-to-trigger effect agree in
+every set. *Corrected in 2.6.0:* 2.5.0 reported that the setting passed on V1 (level 0.97, rank 0.88);
+that analysis compared 90 s of HandoverLab with 120 s of ns-3. 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
@@ -285,8 +295,28 @@ HandoverLab has had this as an option since 1.3.0 (`protocol.rlm_holdoff_s`), on
 covers baseline handover at 3.5 GHz only: 5G-LENA has no conditional handover, DAPS or
 L1/L2-triggered mobility.
 
+To run your own study in both simulators, `handoverlab ns3 export|import|compare` writes the ns-3 package, reads its results back and applies the same checks ([guide](https://github.com/mjs19971997/handoverlab/blob/main/docs/guides/ns3-bridge.md)).
+
 ## What's new
 
+- **2.6.0**: a bridge to ns-3 / 5G-LENA (`handoverlab ns3 export|import|compare`) that writes a ready-to-run
+  ns-3 package for a study, reads its results back and applies the checks of the ns-3 studies
+  ([guide](https://github.com/mjs19971997/handoverlab/blob/main/docs/guides/ns3-bridge.md)). It found an error in 2.5.0: the failure counts of
+  HandoverLab covered 90 s against 120 s of ns-3. Corrected, the ns-3 comparison setting passes the
+  pre-registered checks on none of the three fresh ns-3 sets (level 0.52, 1.31 with rank 0.62, 0.64): the
+  absolute failure level is not calibrated ([correction](https://github.com/mjs19971997/handoverlab/blob/main/docs/calibration.md#correction-in-260-equal-run-lengths)). Handover-rate comparisons were not
+  affected. No change of results.
+- **2.5.0** (corrected in 2.6.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 was reported to pass the
+  pre-registered checks (level 0.97, order 0.88); this compared 90 s of HandoverLab with 120 s of ns-3, and
+  with equal run lengths it fails the order on V1 (rank 0.62) and the level on N3 and V3 (0.52, 0.64), so it
+  is not validated. It is 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 +541,16 @@ 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: an independent, pre-registered validation study: the ns-3 comparison setting for the
+    failure level (its pass on V1 was corrected in 2.6.0: not validated), and the generalisation of the
+    adaptive and learning rules to unseen cards and seeds; no change of results.
+30. **2.6.0 (this release)**: the bridge to ns-3 / 5G-LENA (export, import, compare); the correction of the
+    2.5.0 failure-level comparison (equal run lengths: the absolute failure level is not calibrated); no
+    change of results.
+31. Later (planned, not done), staying a handover simulator: an "ns-3-like" option imitating ns-3's slower
+    out-of-sync detection, judged on a fresh ns-3 set (V4) kept unopened until it is frozen; 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 +560,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 +572,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}
 }
 ```