handoverlab 2.4.0__tar.gz → 2.4.2__tar.gz

handoverlab-2.4.2/.zenodo.json

@@ -0,0 +1,39 @@
+{
+  "title": "HandoverLab: system-level handover simulator for 5G-Advanced and beyond-5G research",
+  "description": "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 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.0 → handoverlab-2.4.2}/CHANGELOG.md

@@ -7,6 +7,62 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [2.4.2] - 2026-10-23
+
+No change of results.
+
+### Added
+
+- A picture for every option, each drawn from a real run by its own script in `tools/`: the handover
+  procedures side by side (`procedures.png`), mobility robustness optimisation (`mro.png`), fast fading
+  (`fading.png`), the slot scheduler with the Numba timings (`scheduler.png`), buffers at handover
+  (`buffers.png`), dual connectivity (`dual-connectivity.png`), UE receive beams (`ue-beams.png`) and the
+  traffic models (`traffic.png`); shown in the README and in each guide.
+- `tools/make_dashboard_screenshots.py`: the dashboard screenshots taken with Edge through the DevTools
+  protocol; all four dashboard pictures redone with this version.
+
+### Fixed
+
+- The speed-ups stated for 2.4.0 ("8 to 60" times, "50-80" times the rate model) were not all supported by the
+  measurements: `docs/performance.md` gives 23 to 59 times for the Numba scheduler and, measured again for 2.4.2
+  on the configuration of the scheduler picture, 42 (round robin) and 93 times (proportional fair), with the
+  NumPy scheduler about 91 times the rate model. The README, `docs/comparison.md`, the scheduler and fading guides
+  and `docs/performance.md` now give these measured numbers.
+
+### Documentation
+
+- 7 GHz calibration: README, `docs/comparison.md`, `docs/calibration-3gpp.md` and
+  `docs/standard-compliance.md` say which cases they count (at 7 GHz 228 percentiles, largest distance
+  1.69-2.43 dB; with the two 6 GHz reruns 342 percentiles, 1.65-2.88 dB).
+- README model boundaries: the slot scheduler (2.2.0) and the user-plane buffers (2.3.0) listed as options,
+  with what is still not modelled.
+- Scenario cards `suburban-sma-7ghz`, `rural-700mhz` and `indoor-office-4ghz`: the 7 GHz calibration of 2.4.0
+  and the hard-LOS results of `docs/guides/indoor-rural.md`; scenario pages regenerated.
+- Examples rerun with this version and their numbers, and where needed their conclusions, updated: the guides
+  on buffers, MRO (the faster MRO setting is no better), beams and layers, indoor and rural scenarios, the
+  learning rule and fast fading; tutorial 2; the README traffic table; the `status` example in the user guide.
+- User guide: all 15 cards, the `a3_pred` rule, `ttt_d2_s`, the layout kinds `indoor` and `ntn`, `run.backend`
+  under `run`, `ntn.hpbw_deg` (tabled widths at 2 GHz only), `ntn.los_model` and `radio.vegetation`; the study
+  example with a main guard. `docs/index.md`: the current layouts and cards. `docs/stability.md`: the missing
+  import. Tutorial 3: the cap of four extensions dates from 2.4.1.
+- Citation with the DOI of 2.4.1.
+
+## [2.4.1] - 2026-10-22
+
+No change of results.
+
+### Fixed
+
+- `examples/study_smoke.yaml`: up to four grid extensions (`max_extensions: 4`); with two the example study
+  stopped at the `grid_edge` gate under the 3GPP defaults of 2.x.
+
+### Documentation
+
+- README: pictures of the 7 GHz calibration, the new scenario cards and predicted measurements; what is new
+  in 2.1.0-2.4.0, the roadmap, the lower-layer options; the citation with the DOI of 2.4.0 and a BibTeX entry.
+- `CITATION.cff` and `.zenodo.json`: description and keywords of the current features.
+- Tutorials 1, 3 and 4 and the report pictures rerun with 2.4.0; status lines name the current release.
+
 ## [2.4.0] - 2026-10-22
 
 ### Added
@@ -1064,7 +1120,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.0...HEAD
+[Unreleased]: https://github.com/mjs19971997/handoverlab/compare/v2.4.2...HEAD
+[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
 [2.3.0]: https://github.com/mjs19971997/handoverlab/compare/v2.2.0...v2.3.0
 [2.2.0]: https://github.com/mjs19971997/handoverlab/compare/v2.1.0...v2.2.0

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

@@ -6,12 +6,15 @@ abstract: >-
   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 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), an L3-filtered
-  measurement chain, a radio-link failure model, an outcome label for every handover attempt,
-  a plug-in interface for handover rules, equal-budget tuning studies with paired statistics,
-  and verification against hand-computed values, golden event-log fingerprints and ns-3 / 5G-LENA.
-version: "2.4.0"
+  cells, along a high-speed railway 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, several carriers and dual connectivity, 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.
+version: "2.4.2"
 doi: 10.5281/zenodo.23409131
 identifiers:
   - type: doi
@@ -23,7 +26,13 @@ identifiers:
   - type: doi
     value: 10.5281/zenodo.23409402
     description: "Version 1.0.1 on Zenodo"
-date-released: 2026-10-22
+  - type: doi
+    value: 10.5281/zenodo.23582521
+    description: "Version 2.4.0 on Zenodo"
+  - type: doi
+    value: 10.5281/zenodo.23585308
+    description: "Version 2.4.1 on Zenodo"
+date-released: 2026-10-23
 license: MIT
 repository-code: "https://github.com/mjs19971997/handoverlab"
 url: "https://mjs19971997.github.io/handoverlab/"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: handoverlab
-Version: 2.4.0
+Version: 2.4.2
 Summary: System-level handover simulator for 5G-Advanced and beyond-5G research
 Author: Mostafa Jalili Sanjarani, Yasser Elmi Sola
 License-Expression: MIT
@@ -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.0.0** (`python -m pip install handoverlab`). The public surface (configuration and
+> **Status: 2.4.2** (`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,
@@ -137,6 +137,60 @@ event D2 of Release 18:
 
 ![The 19 beams on the ground at the start and end of a run, and the received power of each beam at one user](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/ntn-beams.png)
 
+**New cards.** Since 2.3.0: the TR 37.885 urban grid with 35 macro sites 500 m apart (4 GHz), suburban
+macro (SMa) at 7 GHz with 11 sites 1299 m apart and 80 % of the users indoors, and a high-speed train in FR2
+(TR 38.854: 12 remote radio heads 700 m apart, 10 m from the track, 350 km/h):
+
+![Layouts of the cards urban-macro-tr37885-4ghz, suburban-sma-7ghz and hst-fr2-28ghz](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/new-scenarios.png)
+
+**Predicted measurements.** Since 2.4.0 the rule `a3_pred` hands over on predicted L3 results, as studied
+in TR 38.744. Trained on two seeds and tested on two others, the ridge predictor is about 0.5-0.6 dB more
+accurate than sample and hold 400 ms ahead (1.84 / 2.66 / 3.14 dB against 2.38 / 3.26 / 3.74 dB at 30 / 60 /
+90 km/h):
+
+![Prediction error against horizon for the ridge predictor and sample and hold at 30, 60 and 90 km/h](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/ai-mobility.png)
+
+**Handover procedures side by side.** On one card failures fall from 0.6 (A3) to 0.2 (LTM and CLTM) per
+UE-minute; DAPS has no execution interruption; LTM pays with 192 RRC messages per UE-minute against 45 for A3:
+
+![Failures and ping-pong, interruption and RRC messages for A3, CHO, DAPS, LTM and CLTM](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/procedures.png)
+
+**Mobility robustness optimisation.** `a3_mro` moves the offset of every cell pair from its own failures;
+here 17 pairs move and failures fall from 0.22 to 0.14 per UE-minute when starting from 3 dB:
+
+![Cell-pair offsets over time under a3_mro, and failures against fixed A3](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/mro.png)
+
+**Fast fading.** With TDL-A or TDL-C the 5th percentile of the link-monitoring SINR on the ns-3 card falls
+from 8.3 dB to 3.8 and 3.4 dB:
+
+![Received power of one vehicle with no fading, TDL-A and TDL-C, and the distribution of the link-monitoring SINR](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/fading.png)
+
+**Slot scheduler.** Round robin and proportional fair with the MCS, TBS and HARQ of TS 38.214; with
+`run.backend: numba` the same runs take 2.2 s and 1.0 s instead of 92.7 s and 93.3 s with NumPy, with identical
+fingerprints (the default rate model takes about 1.0 s for the same run):
+
+![Delivered rate of each vehicle against its SINR for round robin and proportional fair, and the wall time with NumPy and Numba](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/scheduler.png)
+
+**Buffers at handover.** Without data forwarding A3 loses 2.17 % of the data and DAPS 0.34 %; with
+forwarding nothing is lost, and the forwarded data wait 85-349 ms:
+
+![Lost data with and without forwarding, and the PDCP delay, for A3, CHO, DAPS and LTM](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/buffers.png)
+
+**Dual connectivity.** A 4 GHz master cell and a 30 GHz secondary cell: the secondary cell group carries data
+96 % of the time and 183 Mbit/s per user, against 10.1 Mbit/s on the master cell group:
+
+![One user's 4 GHz master cell and 30 GHz secondary cell over time with the dual-connectivity events, and the procedure rates](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/dual-connectivity.png)
+
+**UE receive beams.** Two panels with DFT beams (peak gain 13.7 dBi) raise the mean SINR from 10.9 to 19.2 dB
+and cut failures from 3.60 to 1.44 per UE-minute; a beam sweep keeps them at 3.36:
+
+![Receive beam patterns of a two-panel UE, and SINR and failures for four UE receive-beam setups](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/ue-beams.png)
+
+**Traffic models.** The same handovers (11.3 per UE-minute) under fixed rates, full buffer, periodic packets and FTP model 3,
+with very different rate, cell load and energy per bit:
+
+![Rate, cell load and energy per bit for the four traffic models](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/traffic.png)
+
 ## What it models
 
 - **Scenarios**: the TR 37.885 urban street grid (configurable number of blocks; 433 m x 250 m
@@ -155,7 +209,11 @@ event D2 of Release 18:
 - **Beams and carriers** (options, 1.10.0): sectors with SSB beams from the TR 38.901 antenna
   model, cell quality from the beams (TS 38.331 5.5.3.3), the serving beam from beam reports, beam
   failure detection and recovery (TS 38.321 5.17, TS 38.133 8.5), several carriers with the
-  measurement periods and gaps of TS 38.133, Event A5 between carriers.
+  measurement periods and gaps of TS 38.133, Event A5 between carriers; UE receive beams (since 2.4.0) and
+  dual connectivity with a secondary cell group (since 2.3.0, TS 37.340).
+- **Lower layers** (options, since 2.2.0): TDL fast fading of TR 38.901 with an effective SINR (MIESM) for
+  link monitoring and the rate; a slot scheduler with the MCS, TBS and HARQ of TS 38.214; user-plane buffers
+  at handover with data forwarding (since 2.3.0, TS 38.300, TS 38.322, TS 38.323).
 - **Mobility**: street-following users with turn probabilities, random waypoints in the open area,
   pedestrian and vehicular speed profiles (by default the urban vehicles of TR 37.885: 60 km/h in one of
   two lanes) or your own speed groups.
@@ -172,7 +230,8 @@ event D2 of Release 18:
   epsilon-greedy bandit (`a3_bandit`, checked against an exhaustive search) and a deep Q-network
   (`dqn`, optional PyTorch).
 - **Failure model**: Qout/Qin with windows, N310/N311/T310, T304, lost commands and configurations,
-  execution failures, re-establishment after a fixed outage (1 s, an assumption), the handover command
+  execution failures, re-establishment after a fixed outage (1 s, inside the bounds of TS 38.133
+  6.2.1.2.1), the handover command
   during T310 as TS 38.331 specifies and the restart of the link monitoring on a new cell as HandoverLab
   reads TS 38.133 8.1.2.2 (defaults since 2.0.0), with options for the link monitoring (own interferer load, ideal random access).
 - **Metrics**: outcome of every attempt (useful, unnecessary, too early, wrong cell, too late,
@@ -195,7 +254,7 @@ the clause-by-clause detail is in [standard compliance](https://github.com/mjs19
 | Channel | TR 38.901 path loss and LOS (UMi, UMa, RMa, SMa, InH), LOS from buildings, spatially consistent LOS and shadowing, car and O2I building penetration loss, radio maps from a file (clause 8), TR 38.811 for the satellite | received power per site and step with a slow time-varying component; indoor users keep the LOS state and shadowing of their position; optional TDL fast fading with effective SINRs (clause 7.7.2, since 2.2.0) | CDL and the full fast-fading model of clause 7.5, MIMO |
 | Beams and carriers | SSB beams per sector, cell quality from beams, beam failure detection and recovery, several carriers with gaps and Event A5; dual connectivity (NR-DC: SN addition, PSCell change, SN release, SCG failure; option since 2.3.0) | the TR 38.901 antenna element and DFT beams; isotropic UE unless UE receive panels are set (option since 2.4.0); the SCG as one PSCell with a full-buffer share | UE transmit beams and polarisation, conditional PSCell change, fast MCG recovery |
 | Mobility | street-following vehicles (60 km/h, two lanes), highway lanes at 70/140 km/h, a train at 350 km/h (TR 38.854), random waypoints, pedestrians | constant speed per user | handheld rotation and body blockage |
-| Traffic and load | constant rates per 5QI, full buffer, periodic, FTP model 3; cell load drives interference | rate from SINR (Shannon-type mapping), no scheduler | slot scheduler, HARQ, RLC/PDCP, TCP and applications |
+| 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 |
@@ -235,7 +294,13 @@ range of the 21 companies that reported their results in the 3GPP contribution R
 Ericsson, Nokia, Samsung, Qualcomm and others), for UMa, UMi and the indoor office at 6 and
 30 GHz. 325 of 342 compared percentiles are inside the range, none is more than about 1 dB from
 the industry mean, and `handoverlab verify` repeats the check
-([details](https://github.com/mjs19971997/handoverlab/blob/main/docs/calibration-3gpp.md)).
+([details](https://github.com/mjs19971997/handoverlab/blob/main/docs/calibration-3gpp.md)). Since 2.4.0 the
+same check runs for Table 7.8-1A against the companies of R1-2506406. At 7 GHz (UMa, UMi and SMa with ISD
+1299 m and 1732 m) all 228 percentiles lie inside their range, but the largest distance from their mean is
+1.69-2.43 dB, which misses the 1.5 dB criterion set before the run; the two 6 GHz reruns of UMa and UMi with
+the updated model add 114 percentiles, also all inside, at 1.65 and 2.88 dB.
+
+![CDFs of coupling loss and geometry for UMa, UMi and SMa at 7 GHz, with the HandoverLab curve inside the company range of R1-2506406](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/calibration_7ghz.png)
 
 ![HandoverLab against the 21 companies of 3GPP R1-165974](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/calibration_38901.png)
 
@@ -280,6 +345,20 @@ L1/L2-triggered mobility.
 
 ## What's new
 
+- **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
+  42 times (`rr`) and 93 times (`pf`) faster than the NumPy loop); the 7 GHz large-scale calibration against the companies of R1-2506406 (every percentile inside the
+  range, the distance to the mean criterion missed); a [comparison with other simulators](https://github.com/mjs19971997/handoverlab/blob/main/docs/comparison.md).
+- **2.3.0**: user-plane buffers at handover (PDCP / RLC, Xn data forwarding for baseline, conditional, DAPS and
+  L1/L2-triggered handover); the TR 37.885 urban macro grid, suburban macro (SMa) and O2I penetration of indoor
+  users; a high-speed train card from TR 38.854; dual connectivity (TS 37.340: SN addition, PSCell change, SN
+  release, SCG failure); a fresh held-out check of the failure model against new ns-3 runs, reported as it
+  came.
+- **2.2.0**: TDL fast fading of TR 38.901 with an effective SINR for link monitoring and rate; a slot scheduler
+  with the MCS, TBS and HARQ of TS 38.214; checked against ns-3 runs with fading.
+- **2.1.0**: a clause-by-clause audit against the full 3GPP texts (`protocol.rrc_detail`,
+  `radio.channel_detail`), value domains from the standards and a study gate that checks them.
 - **2.0.0**: satellites (non-terrestrial networks): one LEO satellite at 600 km with 19 earth-moving beams
   (TR 38.811 channel, TR 38.821 Set-1 S band), conditional handover with the location event D2 of TS 38.331
   Release 18 (`cho_d2`), checked against the link budgets of TR 38.821 (within 0.03 dB). The 3GPP values
@@ -400,13 +479,13 @@ traffic models (one seed, 30 users, 60 s on the urban grid at 10 GHz):
 
 ```text
 model        cell load  rate [Mbit/s]  delivered  SINR [dB]  failures/UE-min
-fixed             0.28          14.25       0.98       24.3             0.12
-full_buffer       0.52         725.93       0.49       21.9             0.08
-periodic          0.28           0.04       0.80       24.4             0.12
-ftp3              0.28           3.93       0.85       24.4             0.12
+fixed             0.28          14.10       0.97       23.6             0.08
+full_buffer       0.52         717.77       0.48       21.2             0.08
+periodic          0.28           0.04       0.86       23.7             0.08
+ftp3              0.28           3.93       0.87       23.7             0.08
 ```
 
-Busier cells interfere more: under full buffer the SINR drops by about 2.5 dB. With one seed each
+Busier cells interfere more: under full buffer the SINR drops by about 2.4 dB. With one seed each
 failure rate counts only a few failures; compare them over several seeds.
 
 The full script is [examples/compare_a3_cho.py](https://github.com/mjs19971997/handoverlab/blob/main/examples/compare_a3_cho.py). Writing your own
@@ -480,19 +559,44 @@ the pages are plain Markdown in [docs/](https://github.com/mjs19971997/handoverl
 20. 1.11.0: the TR 37.885 highway, the card audit, the bandit against an exhaustive search, the
     `dqn` rule and the optional Numba kernel.
 21. 1.12.0: radio maps from ray tracing or measurements.
-22. **2.0.0 (this release)**: a LEO satellite with earth-moving beams and conditional handover with
+22. 2.0.0: a LEO satellite with earth-moving beams and conditional handover with
     event D2; the 3GPP values as defaults, with a switch back to 1.x.
-23. Later (planned, not done): the failure model checked on held-out measurements, the sensitivity of
-    the results to the time step (LTM and beams), a reproducible benchmark package against
-    ns-3 / 5G-LENA, a table of model boundaries, condEventT1 and earth-fixed beams.
+23. 2.1.0: the clause-by-clause standard audit; held-out validation of the failure model, the
+    time-step study, the ns-3 benchmark package and the table of model boundaries.
+24. 2.2.0: fast fading with link-to-system mapping; the slot scheduler with MCS, TBS and HARQ.
+25. 2.3.0: buffers at handover, urban macro, SMa and O2I, the high-speed train, dual connectivity.
+26. 2.4.0: UE receive beams, the TR 38.744 prediction rule, the compiled
+    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;
+    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
+    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.
 
 ## Citation
 
 If you use HandoverLab, please cite it as described in [CITATION.cff](https://github.com/mjs19971997/handoverlab/blob/main/CITATION.cff) (GitHub shows
-it under *Cite this repository*). The releases are archived on Zenodo:
+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); version 1.0.0 is [doi:10.5281/zenodo.23409132](https://doi.org/10.5281/zenodo.23409132)
-and version 1.0.1 [doi:10.5281/zenodo.23409402](https://doi.org/10.5281/zenodo.23409402).
+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
+[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;
+replace version and DOI with those of the version you used.
+
+```bibtex
+@software{handoverlab,
+  author    = {Jalili Sanjarani, Mostafa and Elmi Sola, Yasser},
+  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},
+  url       = {https://github.com/mjs19971997/handoverlab}
+}
+```
 
 ## Licence
 

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

@@ -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.0.0** (`python -m pip install handoverlab`). The public surface (configuration and
+> **Status: 2.4.2** (`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,
@@ -79,6 +79,60 @@ event D2 of Release 18:
 
 ![The 19 beams on the ground at the start and end of a run, and the received power of each beam at one user](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/ntn-beams.png)
 
+**New cards.** Since 2.3.0: the TR 37.885 urban grid with 35 macro sites 500 m apart (4 GHz), suburban
+macro (SMa) at 7 GHz with 11 sites 1299 m apart and 80 % of the users indoors, and a high-speed train in FR2
+(TR 38.854: 12 remote radio heads 700 m apart, 10 m from the track, 350 km/h):
+
+![Layouts of the cards urban-macro-tr37885-4ghz, suburban-sma-7ghz and hst-fr2-28ghz](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/new-scenarios.png)
+
+**Predicted measurements.** Since 2.4.0 the rule `a3_pred` hands over on predicted L3 results, as studied
+in TR 38.744. Trained on two seeds and tested on two others, the ridge predictor is about 0.5-0.6 dB more
+accurate than sample and hold 400 ms ahead (1.84 / 2.66 / 3.14 dB against 2.38 / 3.26 / 3.74 dB at 30 / 60 /
+90 km/h):
+
+![Prediction error against horizon for the ridge predictor and sample and hold at 30, 60 and 90 km/h](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/ai-mobility.png)
+
+**Handover procedures side by side.** On one card failures fall from 0.6 (A3) to 0.2 (LTM and CLTM) per
+UE-minute; DAPS has no execution interruption; LTM pays with 192 RRC messages per UE-minute against 45 for A3:
+
+![Failures and ping-pong, interruption and RRC messages for A3, CHO, DAPS, LTM and CLTM](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/procedures.png)
+
+**Mobility robustness optimisation.** `a3_mro` moves the offset of every cell pair from its own failures;
+here 17 pairs move and failures fall from 0.22 to 0.14 per UE-minute when starting from 3 dB:
+
+![Cell-pair offsets over time under a3_mro, and failures against fixed A3](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/mro.png)
+
+**Fast fading.** With TDL-A or TDL-C the 5th percentile of the link-monitoring SINR on the ns-3 card falls
+from 8.3 dB to 3.8 and 3.4 dB:
+
+![Received power of one vehicle with no fading, TDL-A and TDL-C, and the distribution of the link-monitoring SINR](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/fading.png)
+
+**Slot scheduler.** Round robin and proportional fair with the MCS, TBS and HARQ of TS 38.214; with
+`run.backend: numba` the same runs take 2.2 s and 1.0 s instead of 92.7 s and 93.3 s with NumPy, with identical
+fingerprints (the default rate model takes about 1.0 s for the same run):
+
+![Delivered rate of each vehicle against its SINR for round robin and proportional fair, and the wall time with NumPy and Numba](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/scheduler.png)
+
+**Buffers at handover.** Without data forwarding A3 loses 2.17 % of the data and DAPS 0.34 %; with
+forwarding nothing is lost, and the forwarded data wait 85-349 ms:
+
+![Lost data with and without forwarding, and the PDCP delay, for A3, CHO, DAPS and LTM](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/buffers.png)
+
+**Dual connectivity.** A 4 GHz master cell and a 30 GHz secondary cell: the secondary cell group carries data
+96 % of the time and 183 Mbit/s per user, against 10.1 Mbit/s on the master cell group:
+
+![One user's 4 GHz master cell and 30 GHz secondary cell over time with the dual-connectivity events, and the procedure rates](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/dual-connectivity.png)
+
+**UE receive beams.** Two panels with DFT beams (peak gain 13.7 dBi) raise the mean SINR from 10.9 to 19.2 dB
+and cut failures from 3.60 to 1.44 per UE-minute; a beam sweep keeps them at 3.36:
+
+![Receive beam patterns of a two-panel UE, and SINR and failures for four UE receive-beam setups](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/ue-beams.png)
+
+**Traffic models.** The same handovers (11.3 per UE-minute) under fixed rates, full buffer, periodic packets and FTP model 3,
+with very different rate, cell load and energy per bit:
+
+![Rate, cell load and energy per bit for the four traffic models](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/traffic.png)
+
 ## What it models
 
 - **Scenarios**: the TR 37.885 urban street grid (configurable number of blocks; 433 m x 250 m
@@ -97,7 +151,11 @@ event D2 of Release 18:
 - **Beams and carriers** (options, 1.10.0): sectors with SSB beams from the TR 38.901 antenna
   model, cell quality from the beams (TS 38.331 5.5.3.3), the serving beam from beam reports, beam
   failure detection and recovery (TS 38.321 5.17, TS 38.133 8.5), several carriers with the
-  measurement periods and gaps of TS 38.133, Event A5 between carriers.
+  measurement periods and gaps of TS 38.133, Event A5 between carriers; UE receive beams (since 2.4.0) and
+  dual connectivity with a secondary cell group (since 2.3.0, TS 37.340).
+- **Lower layers** (options, since 2.2.0): TDL fast fading of TR 38.901 with an effective SINR (MIESM) for
+  link monitoring and the rate; a slot scheduler with the MCS, TBS and HARQ of TS 38.214; user-plane buffers
+  at handover with data forwarding (since 2.3.0, TS 38.300, TS 38.322, TS 38.323).
 - **Mobility**: street-following users with turn probabilities, random waypoints in the open area,
   pedestrian and vehicular speed profiles (by default the urban vehicles of TR 37.885: 60 km/h in one of
   two lanes) or your own speed groups.
@@ -114,7 +172,8 @@ event D2 of Release 18:
   epsilon-greedy bandit (`a3_bandit`, checked against an exhaustive search) and a deep Q-network
   (`dqn`, optional PyTorch).
 - **Failure model**: Qout/Qin with windows, N310/N311/T310, T304, lost commands and configurations,
-  execution failures, re-establishment after a fixed outage (1 s, an assumption), the handover command
+  execution failures, re-establishment after a fixed outage (1 s, inside the bounds of TS 38.133
+  6.2.1.2.1), the handover command
   during T310 as TS 38.331 specifies and the restart of the link monitoring on a new cell as HandoverLab
   reads TS 38.133 8.1.2.2 (defaults since 2.0.0), with options for the link monitoring (own interferer load, ideal random access).
 - **Metrics**: outcome of every attempt (useful, unnecessary, too early, wrong cell, too late,
@@ -137,7 +196,7 @@ the clause-by-clause detail is in [standard compliance](https://github.com/mjs19
 | Channel | TR 38.901 path loss and LOS (UMi, UMa, RMa, SMa, InH), LOS from buildings, spatially consistent LOS and shadowing, car and O2I building penetration loss, radio maps from a file (clause 8), TR 38.811 for the satellite | received power per site and step with a slow time-varying component; indoor users keep the LOS state and shadowing of their position; optional TDL fast fading with effective SINRs (clause 7.7.2, since 2.2.0) | CDL and the full fast-fading model of clause 7.5, MIMO |
 | Beams and carriers | SSB beams per sector, cell quality from beams, beam failure detection and recovery, several carriers with gaps and Event A5; dual connectivity (NR-DC: SN addition, PSCell change, SN release, SCG failure; option since 2.3.0) | the TR 38.901 antenna element and DFT beams; isotropic UE unless UE receive panels are set (option since 2.4.0); the SCG as one PSCell with a full-buffer share | UE transmit beams and polarisation, conditional PSCell change, fast MCG recovery |
 | Mobility | street-following vehicles (60 km/h, two lanes), highway lanes at 70/140 km/h, a train at 350 km/h (TR 38.854), random waypoints, pedestrians | constant speed per user | handheld rotation and body blockage |
-| Traffic and load | constant rates per 5QI, full buffer, periodic, FTP model 3; cell load drives interference | rate from SINR (Shannon-type mapping), no scheduler | slot scheduler, HARQ, RLC/PDCP, TCP and applications |
+| 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 |
@@ -177,7 +236,13 @@ range of the 21 companies that reported their results in the 3GPP contribution R
 Ericsson, Nokia, Samsung, Qualcomm and others), for UMa, UMi and the indoor office at 6 and
 30 GHz. 325 of 342 compared percentiles are inside the range, none is more than about 1 dB from
 the industry mean, and `handoverlab verify` repeats the check
-([details](https://github.com/mjs19971997/handoverlab/blob/main/docs/calibration-3gpp.md)).
+([details](https://github.com/mjs19971997/handoverlab/blob/main/docs/calibration-3gpp.md)). Since 2.4.0 the
+same check runs for Table 7.8-1A against the companies of R1-2506406. At 7 GHz (UMa, UMi and SMa with ISD
+1299 m and 1732 m) all 228 percentiles lie inside their range, but the largest distance from their mean is
+1.69-2.43 dB, which misses the 1.5 dB criterion set before the run; the two 6 GHz reruns of UMa and UMi with
+the updated model add 114 percentiles, also all inside, at 1.65 and 2.88 dB.
+
+![CDFs of coupling loss and geometry for UMa, UMi and SMa at 7 GHz, with the HandoverLab curve inside the company range of R1-2506406](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/calibration_7ghz.png)
 
 ![HandoverLab against the 21 companies of 3GPP R1-165974](https://raw.githubusercontent.com/mjs19971997/handoverlab/main/docs/images/calibration_38901.png)
 
@@ -222,6 +287,20 @@ L1/L2-triggered mobility.
 
 ## What's new
 
+- **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
+  42 times (`rr`) and 93 times (`pf`) faster than the NumPy loop); the 7 GHz large-scale calibration against the companies of R1-2506406 (every percentile inside the
+  range, the distance to the mean criterion missed); a [comparison with other simulators](https://github.com/mjs19971997/handoverlab/blob/main/docs/comparison.md).
+- **2.3.0**: user-plane buffers at handover (PDCP / RLC, Xn data forwarding for baseline, conditional, DAPS and
+  L1/L2-triggered handover); the TR 37.885 urban macro grid, suburban macro (SMa) and O2I penetration of indoor
+  users; a high-speed train card from TR 38.854; dual connectivity (TS 37.340: SN addition, PSCell change, SN
+  release, SCG failure); a fresh held-out check of the failure model against new ns-3 runs, reported as it
+  came.
+- **2.2.0**: TDL fast fading of TR 38.901 with an effective SINR for link monitoring and rate; a slot scheduler
+  with the MCS, TBS and HARQ of TS 38.214; checked against ns-3 runs with fading.
+- **2.1.0**: a clause-by-clause audit against the full 3GPP texts (`protocol.rrc_detail`,
+  `radio.channel_detail`), value domains from the standards and a study gate that checks them.
 - **2.0.0**: satellites (non-terrestrial networks): one LEO satellite at 600 km with 19 earth-moving beams
   (TR 38.811 channel, TR 38.821 Set-1 S band), conditional handover with the location event D2 of TS 38.331
   Release 18 (`cho_d2`), checked against the link budgets of TR 38.821 (within 0.03 dB). The 3GPP values
@@ -342,13 +421,13 @@ traffic models (one seed, 30 users, 60 s on the urban grid at 10 GHz):
 
 ```text
 model        cell load  rate [Mbit/s]  delivered  SINR [dB]  failures/UE-min
-fixed             0.28          14.25       0.98       24.3             0.12
-full_buffer       0.52         725.93       0.49       21.9             0.08
-periodic          0.28           0.04       0.80       24.4             0.12
-ftp3              0.28           3.93       0.85       24.4             0.12
+fixed             0.28          14.10       0.97       23.6             0.08
+full_buffer       0.52         717.77       0.48       21.2             0.08
+periodic          0.28           0.04       0.86       23.7             0.08
+ftp3              0.28           3.93       0.87       23.7             0.08
 ```
 
-Busier cells interfere more: under full buffer the SINR drops by about 2.5 dB. With one seed each
+Busier cells interfere more: under full buffer the SINR drops by about 2.4 dB. With one seed each
 failure rate counts only a few failures; compare them over several seeds.
 
 The full script is [examples/compare_a3_cho.py](https://github.com/mjs19971997/handoverlab/blob/main/examples/compare_a3_cho.py). Writing your own
@@ -422,19 +501,44 @@ the pages are plain Markdown in [docs/](https://github.com/mjs19971997/handoverl
 20. 1.11.0: the TR 37.885 highway, the card audit, the bandit against an exhaustive search, the
     `dqn` rule and the optional Numba kernel.
 21. 1.12.0: radio maps from ray tracing or measurements.
-22. **2.0.0 (this release)**: a LEO satellite with earth-moving beams and conditional handover with
+22. 2.0.0: a LEO satellite with earth-moving beams and conditional handover with
     event D2; the 3GPP values as defaults, with a switch back to 1.x.
-23. Later (planned, not done): the failure model checked on held-out measurements, the sensitivity of
-    the results to the time step (LTM and beams), a reproducible benchmark package against
-    ns-3 / 5G-LENA, a table of model boundaries, condEventT1 and earth-fixed beams.
+23. 2.1.0: the clause-by-clause standard audit; held-out validation of the failure model, the
+    time-step study, the ns-3 benchmark package and the table of model boundaries.
+24. 2.2.0: fast fading with link-to-system mapping; the slot scheduler with MCS, TBS and HARQ.
+25. 2.3.0: buffers at handover, urban macro, SMa and O2I, the high-speed train, dual connectivity.
+26. 2.4.0: UE receive beams, the TR 38.744 prediction rule, the compiled
+    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;
+    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
+    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.
 
 ## Citation
 
 If you use HandoverLab, please cite it as described in [CITATION.cff](https://github.com/mjs19971997/handoverlab/blob/main/CITATION.cff) (GitHub shows
-it under *Cite this repository*). The releases are archived on Zenodo:
+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); version 1.0.0 is [doi:10.5281/zenodo.23409132](https://doi.org/10.5281/zenodo.23409132)
-and version 1.0.1 [doi:10.5281/zenodo.23409402](https://doi.org/10.5281/zenodo.23409402).
+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
+[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;
+replace version and DOI with those of the version you used.
+
+```bibtex
+@software{handoverlab,
+  author    = {Jalili Sanjarani, Mostafa and Elmi Sola, Yasser},
+  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},
+  url       = {https://github.com/mjs19971997/handoverlab}
+}
+```
 
 ## Licence
 

{handoverlab-2.4.0 → handoverlab-2.4.2}/docs/calibration-3gpp.md

@@ -91,8 +91,9 @@ InterDigital and ZTE, "Calibration Results for 7 - 24 GHz SI";
 `Calibration_LS_v35`, based on TR 38.901 V19.0.0). The criteria were fixed before the first run: every
 percentile 5-95 % inside the company range widened by 0.5 dB (C1, the rule of the cases above), and the
 largest distance from the company mean at most 1.5 dB per case (C2). Result, 30 000 users per case, seed 1:
-**C1 passes for all 18 case-metric pairs (342 of 342 percentiles strictly inside the range); C2 fails for all
-six cases (largest distance 1.65-2.88 dB).** `handoverlab verify` runs C1 as checks and C2 as notes in the
+**C1 passes for all 18 case-metric pairs of the six cases (342 of 342 percentiles strictly inside the range;
+228 of 228 for the four 7 GHz cases); C2 fails for all six cases (largest distance 1.65-2.88 dB; 1.69-2.43 dB
+for the four 7 GHz cases, 1.65 and 2.88 dB for the two 6 GHz reruns).** `handoverlab verify` runs C1 as checks and C2 as notes in the
 group `calibration`.
 
 **The reference.** `src/handoverlab/verify/data/r1_2506406.csv` keeps, in the format of `r1_165974.csv`, the