handoverlab 2.2.0__tar.gz → 2.4.0__tar.gz

{handoverlab-2.2.0 → handoverlab-2.4.0}/CHANGELOG.md

@@ -7,6 +7,136 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-10-22
+
+### Added
+
+- 7 GHz large-scale calibration (TR 38.901 V19.5.0 clause 7.8.1, Table 7.8-1A) in the `verify` group
+  `calibration`: UMa and UMi at 7 GHz, UMa and UMi at 6 GHz with the updated model, and SMa with ISD 1299 m and
+  1732 m (35 m sites with a mechanical downtilt of 95 / 92 deg through Eqs. 7.1-7 and 7.1-8, 20 % of the users
+  in cars with the car penetration loss, 80 % in residential and commercial buildings over their floors with the
+  low-loss A model), compared with the companies of 3GPP R1-2506406 (RAN1 #122; mean and range in
+  `verify/data/r1_2506406.csv`). Pre-registered result (30 000 users, seed 1): every percentile 5-95 % lies
+  inside the company range (18 of 18 case-metric pairs pass, 342 of 342 percentiles); the largest distance from
+  the company mean is 1.65-2.88 dB, so the second criterion (at most 1.5 dB) fails for all six cases. It is
+  reported as a note. The checks against R1-165974 are unchanged. `simulate_drops` takes the IRR-glass loss of
+  the case's reference when `irr_glass` is not given (unchanged for the old cases).
+- Compiled slot scheduler: with `run.backend: numba` (`pip install handoverlab[fast]`) the slots of
+  `protocol.scheduler` are played by a compiled loop (`handoverlab.engine._kernels.sched_slots`). The MCS
+  look-ups, logarithms and block error probabilities still come from the NumPy functions of the reference loop
+  (per-interval tables), and the loop uses only basic arithmetic in the reference order, so every result is
+  bit-identical to the NumPy loop (`tests/test_sched_kernel.py`, which also runs the loop's logic as plain Python
+  without Numba). On the ns-3 card the engine time with the scheduler drops by a factor of 8 to 60 (case and machine load) (about 3 times the rate model instead of 50-80 times; see `docs/performance.md`). The NumPy loop stays the reference and the default and runs in debug mode.
+- UE receive beams as an option of the beam model (`radio.beams.ue_panels` 1, 2 or 4, off by default): UE panels
+  of TR 38.802 V14.2.0 Table A.2.1-4 (Config 1: two panels 180 deg apart, Config 2: four at 90 deg; `ue_panel`
+  [M, N] = [2, 4] at half a wavelength, one polarisation) with the element of Table A.2.1-8 (model 1, 5 dBi;
+  = ITU-R M.2412-0 Table 11), `ue_beams` DFT receive beams per panel over `ue_beam_span_deg`, bearing uniform
+  per UE (`ue_orientation: random`) or along the direction of travel (`heading`). Measurements use the best
+  receive beam of the best panel (`ue_rx: best`; TS 38.215 5.1.1 receiver branches) or a sweep over the beams,
+  one per L1 instant, with the highest of the last samples reported (`sweep`); data, RLM, beam failure
+  detection and recovery and the interference use the serving receive beam. The FR2 time scaling of the sweep
+  was already in `protocol.meas_periods: ts38133` (Mmeas_period_w/o_gaps = 24, TS 38.133 V19.6.0 9.2.5.1) and is
+  not applied twice; `sweep` is refused with `ts38133`. New random stream `ue_beams`. Not combined with
+  `protocol.dc`. With the option off every result is unchanged. Guide: `docs/guides/ue-beams.md`.
+- AI/ML-based mobility after 3GPP TR 38.744 V19.0.1 (Release 19) as an optional rule, `a3_pred` (NumPy only, off
+  unless a run names it): prediction of the L3 cell-level RSRP of a cell from its own past L3 results (RRM
+  sub-use case 2), in case A (prediction window ahead; handover on the predicted Event A3, handover model
+  option 2 with the preparation started at the report) and case B (measurement skipping with MRRT =
+  skip / (skip + 1), L3 filtering options 1-3, Event A3 on the measured-and-predicted series, option 3).
+  Predictors: sample and hold (the non-AI baseline of TR 38.744 clause 5.1) and a ridge-regression
+  autoregressive model trained on runs of training seeds (`handoverlab.rules.predict.fit_predictor`,
+  `collect`, JSON weights), or a user object. Statistics after a run (`PredA3.stats`, `Recorder`): prediction
+  accuracy per horizon against the fully measured L3 result, MRRT, and the counters n1, n2, n3 and F1 score of
+  the indirect A3 event prediction (clause 5.3.1). With `act: false` and in case B without skipping the rule
+  gives the event log of `a3`. `handoverlab verify --only learning` gained four checks (P1-P4). Guide
+  `docs/guides/ai-mobility.md` with the evaluation against TR 38.744 and what is not modelled (RLF
+  prediction, frequency- and spatial-domain prediction, beam-level prediction, option 1, LCM); compliance rows
+  in `docs/standard-compliance.md`. Pre-registered evaluation (FR1 case B, FR2 case A): ridge more accurate
+  than sample and hold, errors rising with speed, PW and MRRT as TR 38.744 observes; MRRT 50 % costs
+  +0.7-0.9 percentage points of HOF rate; option 2 cuts the HOF rate from 2.4 % to 0.3 % but with 55 % more
+  attempts and three times the ping-pongs, and sample and hold does the same; generalization criterion G2
+  failed. Every existing result is unchanged.
+
+### Documentation
+
+- `docs/comparison.md`: HandoverLab next to ns-3 with 5G-LENA and the mmWave module, Simu5G, the Vienna 5G System
+  Level Simulator, the MATLAB 5G Toolbox, OpenAirInterface and Sionna on the points that matter for handover
+  studies (A3, CHO, DAPS, LTM, radio-link failure, dual connectivity, NTN, beams, fast fading and link-to-system
+  mapping, scheduler, speed and scale, licence, language, last release, validation against 3GPP). Every cell
+  about another tool cites its official documentation, repository or paper (accessed 2026-10-22); facts not
+  found are marked "not stated"; a section lists where the other tools are stronger.
+
+## [2.3.0] - 2026-10-22
+
+### Added
+
+- User-plane buffers at handover as an option (`protocol.buffers`: `am` or `um`, off by default): one downlink
+  bearer per user whose PDCP data wait in a FIFO at the gNB, data forwarding over Xn (`protocol.forwarding`,
+  `protocol.xn_delay_s`) for baseline handover, CHO and LTM / CLTM (late forwarding after HANDOVER SUCCESS unless
+  `protocol.early_forwarding`) and DAPS (the source keeps sending, copies to the target), re-establishment with
+  and without forwarding, the PDCP discard timer of TS 38.331 (`protocol.discard_timer_s`), and with the slot
+  scheduler the HARQ data at a MAC reset (lost with RLC UM, re-sent with AM) and TBs lost after the last HARQ
+  transmission. Sources: TS 38.300 V19.4.0 9.2.3.1-9.2.3.7, TS 38.322 V19.2.0 4.4 / 5.1.2, TS 38.323 V19.1.0
+  5.1.2 / 5.3 / 5.5. New metrics `pdcp_delivered_kbyte_pm`, `pdcp_lost_*`, `pdcp_forwarded_*`, `pdcp_delay_ms`,
+  `pdcp_delay_p95_ms`, `pdcp_delay_forwarded_ms` (0 without the option). Base engine only. With the option off
+  every result is unchanged. Guide: `docs/guides/buffers.md`.
+- Suburban macro (SMa) of TR 38.901 V19.5.0 (`radio.pathloss: sma`, 0.5-37 GHz): the LOS and NLOS path loss of
+  Table 7.4.1-1 (h = 10 m, W = 10 m; the NLOS row is used as printed, without a max() with the LOS loss, so for a
+  UT high up close to a site NLOS can lie below LOS) and the LOS probability of Table 7.4.2-1 with the vegetation
+  density `radio.vegetation` (0, 0.1, 0.2); heights checked against the applicability ranges (25-35 m, 1-14 m).
+- O2I building penetration loss of indoor users (TR 38.901 clause 7.4.3.1): a speed group with `indoor: true`
+  marks indoor users; each gets PL_tw + 0.5 d2D-in + N(0, sigma_P^2) on all its links, drawn once
+  (`radio.o2i_model`: `low`, `high`, `low_a` for SMa, or `mixed`; `radio.o2i_d_in_max_m`; SMa residential /
+  commercial buildings 90 % / 10 %), from its own random stream; an indoor user gets no car penetration loss.
+  The LOS state and the shadowing of an indoor user stay those of its position (stated abstraction, measured by
+  `verify`).
+- `radio.building_los: false` on the street grid: sites above the rooftops, the LOS state from the LOS probability
+  alone (TR 37.885 clause 6.2.1); `radio.env_height_m`: one effective environment height for the UMa / UMi
+  breakpoint (TR 37.885: 0.25 m).
+- Scenario cards `urban-macro-tr37885-4ghz` (the TR 37.885 urban grid below 6 GHz with 500 m macro sites on the
+  hexagonal layout of TR 36.885 Figure A.1.3-1, UMa at 4 GHz, h_E 0.25 m, vehicles at 60 km/h; the wrap-around is
+  replaced by the lattice sites within 1000 m of the grid) and `suburban-sma-7ghz` (11 SMa sites at 1299 m,
+  7 GHz, 80 % indoor users with the low-loss A model, 20 % in cars). Guide: `docs/guides/suburban-o2i.md`.
+- Optional `verify` group `scenarios` (`--only scenarios`; criteria fixed before the first run), reported as it
+  came: 7 pass, 3 fail. The urban macro coupling gain lies 0.3-1.2 dB below an independent computation around
+  the median in every block of seeds (cause open; the LOS share close to the sites is a little low); the check
+  of the outdoor SMa users fails on sampling noise (40 seeds pooled: within 0.54 dB); a TR-exact treatment of
+  indoor users (LOS at d2D-out, O2I shadowing 8 dB) gives a 2.0 dB wider upper tail (95 % point) than the
+  simulator's abstraction, with the median within 0.1 dB.
+- Scenario card `hst-fr2-28ghz`: the FR2 high-speed train of TR 38.854 V18.0.0 as its system-level mobility
+  study sets it up (Table 6.3.8.1-1): one train with one roof-mounted CPE at 350 km/h on a straight track, an RRH
+  every 700 m on one side, 10 m from the track (Scenario-A), one panel of 8 x 8 elements with one SSB beam per RRH
+  pointing along the track at the next RRH, every RRH its own cell (L3 handover, no DPS), 28 GHz, 50 MHz,
+  120 kHz, 31 dBm, TR 38.901 RMa LOS only, no inter-cell interference, N310 = N311 = 2 and the TS 38.133
+  measurement periods of the legacy requirements (480 ms). Guide: `docs/guides/high-speed-train.md`, with the
+  pre-registered comparison against the TR's results.
+- `radio.beams.am_db`: A_m of the TR 38.901 Table 7.3-1 element pattern (default 30 dB, unchanged results); a
+  larger value lowers the back lobe, as the antenna "without back lobe" of the TR 38.854 mobility study.
+- Dual connectivity as an option (`protocol.dc`, off by default): NR-DC of TS 37.340 V19.3.0 with the master cell
+  group on the scenario's other carriers and a secondary cell group (one PSCell) on the cells of one layer of
+  `radio.layers`: SN addition on event A4 (clause 10.2), PSCell change on event A3 (clauses 10.5, 10.6) and SN
+  release (clause 10.4), each prepared between the nodes and sent over the MCG, random access on the PSCell under
+  T304; separate radio-link monitoring and SCG radio-link failure (TS 38.331 5.3.10.3); SCG failures reported to
+  the MN, which releases the SCG (clause 7.7); an MCG failure releases the SCG (TS 38.331 5.3.7.2); at an MCG
+  handover the SN is kept or released (`on_mcg_ho`, clause 10.7). The MCG behaves exactly as without the SCG.
+  New metrics `sn_additions_pm`, `sn_addition_failures_pm`, `pscell_changes_pm`, `pscell_change_failures_pm`,
+  `sn_releases_pm`, `scg_rlf_pm`, `scg_failures_pm`, `scg_released_by_mcg_pm`, `scg_time_share`,
+  `scg_rate_mbps`, `pscell_change_interruption_s_pm`, `dc_rrc_messages_pm` (zero without the option). Guide:
+  `docs/guides/dual-connectivity.md`, with what is left out.
+
+### Documentation
+
+- Fresh held-out check N3 of the failure model on 40 new ns-3 runs, limits fixed before the runs: a fixed
+  link-monitoring interferer load (`protocol.lm_load` 0.15, chosen on the earlier runs) raises the failure level
+  from 0.16 to 0.47 of ns-3's and the failure order from 0.78 to 0.95; the level check (0.67-1.5) fails, so the
+  setting is reported, not adopted. The recovery time after a failure is set against the bounds of TS 38.133
+  clause 6.2.1.2.1 (about 0.28-1.55 s), which the default 1.0 s meets. `docs/calibration.md`.
+
+### Not done
+
+- The 7 GHz large-scale calibration of TR 38.901 clause 7.8.1 (Table 7.8-1A): the TR gives the results only by
+  reference to R1-2506406, which this release does not include.
+
 ## [2.2.0] - 2026-10-22
 
 ### Added
@@ -934,7 +1064,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.2.0...HEAD
+[Unreleased]: https://github.com/mjs19971997/handoverlab/compare/v2.4.0...HEAD
+[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
 [2.1.0]: https://github.com/mjs19971997/handoverlab/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/mjs19971997/handoverlab/compare/v1.12.0...v2.0.0

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

@@ -11,7 +11,7 @@ abstract: >-
   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.2.0"
+version: "2.4.0"
 doi: 10.5281/zenodo.23409131
 identifiers:
   - type: doi

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: handoverlab
-Version: 2.2.0
+Version: 2.4.0
 Summary: System-level handover simulator for 5G-Advanced and beyond-5G research
 Author: Mostafa Jalili Sanjarani, Yasser Elmi Sola
 License-Expression: MIT
@@ -142,10 +142,12 @@ event D2 of Release 18:
 - **Scenarios**: the TR 37.885 urban street grid (configurable number of blocks; 433 m x 250 m
   pitch, 20 m streets) with sites on the pavement, an open area with a hexagonal site grid, the
   TR 37.885 highway (since 1.11.0 with wrap-around, LOS-only links and both site layouts of
-  TR 36.885, below and above 6 GHz), the TR 38.901 indoor office, rural macro cells, a LEO satellite with
+  TR 36.885, below and above 6 GHz), the TR 37.885 urban grid with 500 m macro sites (since 2.3.0), the
+  TR 38.901 indoor office, rural and suburban (SMa, since 2.3.0) macro cells, a LEO satellite with
   earth-moving beams (since 2.0.0, TR 38.811 and TR 38.821), explicit site lists, and built-in scenario
   cards (`handoverlab scenarios`).
-- **Channel**: TR 38.901 UMi street canyon, UMa, RMa and InH-Office path loss (LOS/NLOS); line of sight from the
+- **Channel**: TR 38.901 UMi street canyon, UMa, RMa, SMa (since 2.3.0) and InH-Office path loss (LOS/NLOS); O2I
+  building penetration loss of indoor users (since 2.3.0); line of sight from the
   building geometry plus the spatially consistent LOS state, hard or soft; spatially correlated shadowing; a
   time-varying component; L1 measurement error; beam gain and load-coupled interference;
   optionally a penetration loss per user (in-car loss of TR 38.901); or, since 1.12.0, your own radio
@@ -189,19 +191,20 @@ the clause-by-clause detail is in [standard compliance](https://github.com/mjs19
 
 | Part | Modelled | Abstracted | Not modelled |
 |---|---|---|---|
-| Layouts | `street_grid` (TR 37.885 urban grid), `open_area`, `highway` (TR 37.885 / TR 36.885, wrap-around), `indoor` (TR 38.901 office), `ntn` (one LEO satellite, TR 38.821); explicit site lists | sites on the pavement with small cells (urban cards) | the 500 m macro grid of the TR 37.885 urban scenario, several satellites |
-| Channel | TR 38.901 path loss and LOS (UMi, UMa, RMa, InH), LOS from buildings, spatially consistent LOS and shadowing, 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; 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 | the TR 38.901 antenna element and DFT beams; isotropic UE | UE-side beamforming, dual connectivity and PSCell change |
-| Mobility | street-following vehicles (60 km/h, two lanes), highway lanes at 70/140 km/h, random waypoints, pedestrians | constant speed per user | handheld rotation and body blockage |
+| Layouts | `street_grid` (TR 37.885 urban grid), `open_area`, `highway` (TR 37.885 / TR 36.885, wrap-around), `indoor` (TR 38.901 office), `ntn` (one LEO satellite, TR 38.821); explicit site lists | sites on the pavement with small cells (urban cards); the TR 37.885 urban macro grid without wrap-around (`urban-macro-tr37885-4ghz`) | several satellites |
+| 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 |
 | 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`, `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 |
+| 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 |
 | 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`,
 `open-area-10ghz`, `ns3-urban-3.5ghz`, `highway-tr37885-4ghz`, `highway-tr37885-30ghz`, `indoor-office-4ghz`,
-`rural-700mhz`, `ntn-leo600-2ghz`; each names the source of every value and its own limitations.
+`rural-700mhz`, `ntn-leo600-2ghz`, `urban-macro-tr37885-4ghz`, `suburban-sma-7ghz`, `hst-fr2-28ghz`; each
+names the source of every value and its own limitations.
 
 ## Scope: 5G-Advanced and beyond 5G
 
@@ -215,7 +218,8 @@ networks with small cells 50-300 m apart. Three paths lead beyond 5G:
 - **Non-terrestrial networks**: a LEO satellite with earth-moving beams (TR 38.811, TR 38.821) and conditional
   handover with condEventD2 (TS 38.331 Release 18).
 - **Learning-based mobility**: the rule interface gives a rule every measurement and the outcome of every
-  attempt; `a3_bandit` and `dqn` are examples, `a3_mro` the fair tuned baseline.
+  attempt; `a3_bandit` and `dqn` are examples, `a3_mro` the fair tuned baseline, and `a3_pred` follows the
+  RRM measurement prediction of TR 38.744 (Release 19).
 
 6G itself is at the stage of requirements: TR 38.914 V20.1.0 (Release 20, last changed at RAN #113 in September
 2026) sets scenarios and key performance requirements but specifies no handover procedure, timer or measurement
@@ -431,6 +435,10 @@ the pages are plain Markdown in [docs/](https://github.com/mjs19971997/handoverl
 - [Scenario cards](https://github.com/mjs19971997/handoverlab/tree/main/docs/scenarios): the built-in scenarios with the source of every parameter.
 - [Verification](https://github.com/mjs19971997/handoverlab/blob/main/docs/verification.md), [failure-model calibration](https://github.com/mjs19971997/handoverlab/blob/main/docs/calibration.md) and
   [performance](https://github.com/mjs19971997/handoverlab/blob/main/docs/performance.md).
+- [Comparison with other simulators](https://github.com/mjs19971997/handoverlab/blob/main/docs/comparison.md): ns-3 with 5G-LENA
+  and the mmWave module, Simu5G, the Vienna 5G System Level Simulator, the MATLAB 5G Toolbox, OpenAirInterface
+  and Sionna on handover procedures, failure model, NTN, beams, PHY abstraction, scheduler, scale and validation,
+  each cell with its source, including where the other tools are stronger.
 - [Changelog](https://github.com/mjs19971997/handoverlab/blob/main/CHANGELOG.md), [contribution guide](https://github.com/mjs19971997/handoverlab/blob/main/CONTRIBUTING.md) and [releasing](https://github.com/mjs19971997/handoverlab/blob/main/docs/RELEASING.md).
 
 ## Roadmap

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

@@ -84,10 +84,12 @@ event D2 of Release 18:
 - **Scenarios**: the TR 37.885 urban street grid (configurable number of blocks; 433 m x 250 m
   pitch, 20 m streets) with sites on the pavement, an open area with a hexagonal site grid, the
   TR 37.885 highway (since 1.11.0 with wrap-around, LOS-only links and both site layouts of
-  TR 36.885, below and above 6 GHz), the TR 38.901 indoor office, rural macro cells, a LEO satellite with
+  TR 36.885, below and above 6 GHz), the TR 37.885 urban grid with 500 m macro sites (since 2.3.0), the
+  TR 38.901 indoor office, rural and suburban (SMa, since 2.3.0) macro cells, a LEO satellite with
   earth-moving beams (since 2.0.0, TR 38.811 and TR 38.821), explicit site lists, and built-in scenario
   cards (`handoverlab scenarios`).
-- **Channel**: TR 38.901 UMi street canyon, UMa, RMa and InH-Office path loss (LOS/NLOS); line of sight from the
+- **Channel**: TR 38.901 UMi street canyon, UMa, RMa, SMa (since 2.3.0) and InH-Office path loss (LOS/NLOS); O2I
+  building penetration loss of indoor users (since 2.3.0); line of sight from the
   building geometry plus the spatially consistent LOS state, hard or soft; spatially correlated shadowing; a
   time-varying component; L1 measurement error; beam gain and load-coupled interference;
   optionally a penetration loss per user (in-car loss of TR 38.901); or, since 1.12.0, your own radio
@@ -131,19 +133,20 @@ the clause-by-clause detail is in [standard compliance](https://github.com/mjs19
 
 | Part | Modelled | Abstracted | Not modelled |
 |---|---|---|---|
-| Layouts | `street_grid` (TR 37.885 urban grid), `open_area`, `highway` (TR 37.885 / TR 36.885, wrap-around), `indoor` (TR 38.901 office), `ntn` (one LEO satellite, TR 38.821); explicit site lists | sites on the pavement with small cells (urban cards) | the 500 m macro grid of the TR 37.885 urban scenario, several satellites |
-| Channel | TR 38.901 path loss and LOS (UMi, UMa, RMa, InH), LOS from buildings, spatially consistent LOS and shadowing, 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; 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 | the TR 38.901 antenna element and DFT beams; isotropic UE | UE-side beamforming, dual connectivity and PSCell change |
-| Mobility | street-following vehicles (60 km/h, two lanes), highway lanes at 70/140 km/h, random waypoints, pedestrians | constant speed per user | handheld rotation and body blockage |
+| Layouts | `street_grid` (TR 37.885 urban grid), `open_area`, `highway` (TR 37.885 / TR 36.885, wrap-around), `indoor` (TR 38.901 office), `ntn` (one LEO satellite, TR 38.821); explicit site lists | sites on the pavement with small cells (urban cards); the TR 37.885 urban macro grid without wrap-around (`urban-macro-tr37885-4ghz`) | several satellites |
+| 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 |
 | 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`, `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 |
+| 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 |
 | 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`,
 `open-area-10ghz`, `ns3-urban-3.5ghz`, `highway-tr37885-4ghz`, `highway-tr37885-30ghz`, `indoor-office-4ghz`,
-`rural-700mhz`, `ntn-leo600-2ghz`; each names the source of every value and its own limitations.
+`rural-700mhz`, `ntn-leo600-2ghz`, `urban-macro-tr37885-4ghz`, `suburban-sma-7ghz`, `hst-fr2-28ghz`; each
+names the source of every value and its own limitations.
 
 ## Scope: 5G-Advanced and beyond 5G
 
@@ -157,7 +160,8 @@ networks with small cells 50-300 m apart. Three paths lead beyond 5G:
 - **Non-terrestrial networks**: a LEO satellite with earth-moving beams (TR 38.811, TR 38.821) and conditional
   handover with condEventD2 (TS 38.331 Release 18).
 - **Learning-based mobility**: the rule interface gives a rule every measurement and the outcome of every
-  attempt; `a3_bandit` and `dqn` are examples, `a3_mro` the fair tuned baseline.
+  attempt; `a3_bandit` and `dqn` are examples, `a3_mro` the fair tuned baseline, and `a3_pred` follows the
+  RRM measurement prediction of TR 38.744 (Release 19).
 
 6G itself is at the stage of requirements: TR 38.914 V20.1.0 (Release 20, last changed at RAN #113 in September
 2026) sets scenarios and key performance requirements but specifies no handover procedure, timer or measurement
@@ -373,6 +377,10 @@ the pages are plain Markdown in [docs/](https://github.com/mjs19971997/handoverl
 - [Scenario cards](https://github.com/mjs19971997/handoverlab/tree/main/docs/scenarios): the built-in scenarios with the source of every parameter.
 - [Verification](https://github.com/mjs19971997/handoverlab/blob/main/docs/verification.md), [failure-model calibration](https://github.com/mjs19971997/handoverlab/blob/main/docs/calibration.md) and
   [performance](https://github.com/mjs19971997/handoverlab/blob/main/docs/performance.md).
+- [Comparison with other simulators](https://github.com/mjs19971997/handoverlab/blob/main/docs/comparison.md): ns-3 with 5G-LENA
+  and the mmWave module, Simu5G, the Vienna 5G System Level Simulator, the MATLAB 5G Toolbox, OpenAirInterface
+  and Sionna on handover procedures, failure model, NTN, beams, PHY abstraction, scheduler, scale and validation,
+  each cell with its source, including where the other tools are stronger.
 - [Changelog](https://github.com/mjs19971997/handoverlab/blob/main/CHANGELOG.md), [contribution guide](https://github.com/mjs19971997/handoverlab/blob/main/CONTRIBUTING.md) and [releasing](https://github.com/mjs19971997/handoverlab/blob/main/docs/RELEASING.md).
 
 ## Roadmap

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

@@ -81,6 +81,58 @@ distribution, at most 0.12 dB below the smallest company value: the SIR of Hando
 0.5 dB below the industry mean there, which is on the conservative side. `handoverlab verify`
 passes a case when every percentile lies inside the company range widened by 0.5 dB.
 
+## 7 GHz: Table 7.8-1A against R1-2506406 (since 2.4.0)
+
+**Summary.** TR 38.901 V19.5.0 adds Table 7.8-1A to clause 7.8.1: UMa, UMi-Street Canyon and suburban macro
+(SMa, ISD 1299 m and 1732 m) at 7 GHz, plus UMa and UMi at 6 GHz again "with updated channel modeling". The
+companies reported their CDFs in the 3GPP contribution **R1-2506406** (RAN1 #122, Bengaluru, August 2025,
+InterDigital and ZTE, "Calibration Results for 7 - 24 GHz SI";
+[3GPP server](https://www.3gpp.org/ftp/tsg_ran/WG1_RL1/TSGR1_122/Docs/R1-2506406.zip); large-scale workbook
+`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
+group `calibration`.
+
+**The reference.** `src/handoverlab/verify/data/r1_2506406.csv` keeps, in the format of `r1_165974.csv`, the
+mean, the smallest and the largest company value and the number of companies per case, metric and percentile;
+the mean equals the workbook's own mean column. Companies with complete columns: 16 (coupling loss) / 15
+(SINR, SIR) at 6 GHz; 17 / 16 for UMa and UMi at 7 GHz (Huawei, InterDigital, Samsung, ZTE, CATT, Lenovo,
+Apple, Nokia, Ericsson, OPPO, MediaTek, Intel, Sharp, Spreadtrum, LGE, ETRI, Xiaomi; Spreadtrum gave the
+coupling loss only); 17 / 16 for SMa 1299 m (with vivo, without ETRI); 13 / 12 for SMa 1732 m.
+
+**The drop.** UMa and UMi as above (Table 7.8-1), with the IRR-glass loss of V19.5.0 (25.4 + 0.11 f dB) because
+the companies worked with Release 19; at 7 GHz 49 dBm (UMa) and 44 dBm (UMi) with 20 MHz, the 6 GHz values of
+Table 7.8-1, which Table 7.8-1A leaves unchanged for these two scenarios. SMa:
+
+| Item | Setting | Source |
+|---|---|---|
+| Layout | 19 sites, 3 sectors, ISD 1299 m or 1732 m, BS 35 m, geographical wrap-around, minimum 2D distance 35 m (to d2D-out) | Tables 7.2-5, 7.8-1A |
+| Antenna | element of Table 7.3-1 and 10 vertical elements (one port) without electrical tilt, the panel tilted mechanically to 95 deg (ISD 1299 m) or 92 deg (ISD 1732 m): the angles are taken into the antenna's local coordinates with Eqs. 7.1-7 and 7.1-8 | Tables 7.3-1, 7.8-1A; clause 7.1.3 |
+| Users | 20 % outdoors (in cars, 1.5 m) with the car penetration loss N(9 dB, 5 dB) of non-metallic windows; 80 % indoors, 90 % of them in residential buildings (1.5 or 4.5 m), 10 % in commercial buildings (1.5 ... 13.5 m), uniform over the floors | Tables 7.2-5, 7.8-1A; clause 7.4.3.2 |
+| O2I loss | low-loss A model (30 % glass, 70 % plywood, sigma_P 4.4 dB); d2D-in = minimum of two uniform variables up to 10 m (residential) or 25 m (commercial) | clause 7.4.3.1, Tables 7.4.3-1, 7.4.3-2 |
+| Path loss, LOS, shadowing | the SMa models of `handoverlab.channel.pathloss` (Table 7.4.1-1; LOS probability of Table 7.4.2-1 without vegetation); shadowing 4 dB (LOS below d_BP), 6 dB (LOS beyond), 8 dB (NLOS), 8 dB for indoor users | Tables 7.4.1-1, 7.4.2-1, 7.5-6 Part-4 |
+| Link budget | 49 dBm, 20 MHz, UT noise figure 9 dB, isotropic UT, attachment to the highest coupling gain | Tables 7.8-1, 7.8-1A |
+
+Results (median HandoverLab / company mean; percentiles 5-95 % strictly inside the range; largest distance
+from the mean):
+
+| Case | Coupling loss [dB] | SINR [dB] | SIR [dB] | C1 | C2 (largest distance) |
+|---|---|---|---|---|---|
+| UMa-6 GHz | 119.9 / 121.0; 19/19; 1.65 | 5.5 / 5.6; 19/19; 1.34 | 8.0 / 8.0; 19/19; 0.17 | pass | fail (1.65) |
+| UMi-6 GHz | 111.9 / 112.1; 19/19; 2.88 | 5.1 / 5.2; 19/19; 1.35 | 6.8 / 6.6; 19/19; 0.53 | pass | fail (2.88) |
+| UMa-7 GHz | 121.7 / 122.4; 19/19; 1.78 | 5.0 / 5.0; 19/19; 0.90 | 7.9 / 7.9; 19/19; 0.29 | pass | fail (1.78) |
+| UMi-7 GHz | 113.8 / 113.3; 19/19; 2.43 | 4.7 / 4.8; 19/19; 1.63 | 6.7 / 6.6; 19/19; 0.30 | pass | fail (2.43) |
+| SMa-7 GHz, ISD 1299 m | 103.5 / 104.3; 19/19; 1.31 | 5.9 / 5.7; 19/19; 1.69 | 5.9 / 5.9; 19/19; 1.57 | pass | fail (1.69) |
+| SMa-7 GHz, ISD 1732 m | 109.2 / 111.3; 19/19; 2.24 | 6.3 / 5.9; 19/19; 1.07 | 6.4 / 6.6; 19/19; 0.32 | pass | fail (2.24) |
+
+Where the distance comes from: for UMa and UMi the coupling loss of the best users (75-95 %, close to a site)
+is 1.6-2.9 dB lower than the company mean, and at UMi 7 GHz also at 5-10 %; the medians are within 1.1 dB.
+For SMa 1732 m the coupling loss is about 2.1 dB lower than the mean over most of the distribution. The
+company spread is large here (at the median, from 106.5 dB to 129.4 dB for SMa 1732 m), so the mean is a soft
+target, but C2 was fixed before the run and is reported as it came. No parameter was changed after the run.
+
 ## What this calibration covers, and what it does not
 
 - It covers the **radio model**: the path-loss formulas, the LOS probabilities, the shadowing, the
@@ -98,8 +150,8 @@ passes a case when every percentile lies inside the company range widened by 0.5
 ## Repeat it
 
 ```bash
-handoverlab verify --only calibration          # 10 000 users per case, a few seconds
-handoverlab verify --only calibration --full   # 30 000 users per case, the table above
+handoverlab verify --only calibration          # 10 000 users per case, under a minute
+handoverlab verify --only calibration --full   # 30 000 users per case, the tables above
 python tools/make_calibration_figure.py        # docs/images/calibration_38901.png
 ```
 
@@ -110,4 +162,6 @@ case = cal.CalScenario("UMa", 6.0)
 res = cal.simulate_drops(case, n_users=30000, seed=1)
 for c in cal.compare(case, res):
     print(c.metric, c.inside.sum(), "of", len(c.percentiles), "inside, largest distance", c.max_dev_db)
+
+case = cal.CalScenario("SMa", 7.0, isd_m=1299.0, reference="R1-2506406")   # compared with R1-2506406
 ```

{handoverlab-2.2.0 → handoverlab-2.4.0}/docs/calibration.md

@@ -22,11 +22,38 @@ registered (2.1.0 defaults gave the same verdicts):
 | Recovery: time without connection per failure | 0.09 s | 1.0 s (`reest_s`) | ratio 0.67-1.5 | fails |
 | Execution failures | none in any cell | 0-5 % | needs 10 in ns-3 | not measurable |
 
-The two failing parts explain much of the failure gap: HandoverLab's full-buffer load always fills
-every cell, so interference is far higher than with ns-3's offered traffic (ns-3 has fewer failures
-at full traffic, 90 to 34 and 13 to 3; HandoverLab many more, 18 to 521 and 4 to 175), and a
-re-establishment takes a fixed second. A traffic-driven load and a recovery time from the standard
-texts are the next steps; they need new ns-3 runs to be judged, as these runs have now been seen.
+ns-3's full traffic is an overload too (more than a cell can carry), so both simulators fill the
+cells; the difference is what link monitoring sees. In ns-3 its SINR hardly moves with the data
+load; in HandoverLab it follows the data load by default (ns-3 has fewer failures at full traffic,
+90 to 34 and 13 to 3; HandoverLab many more, 18 to 521 and 4 to 175). TS 38.133 V19.6.0 clause 8.1
+evaluates the link on a hypothetical PDCCH, and the neighbours' control channels and reference
+signals are sent whatever the data load; `protocol.lm_load` gives link monitoring such a fixed
+interferer load.
+
+On recovery, the standard does not fix one value: TS 38.133 V19.6.0 clause 6.2.1.2.1 bounds the
+re-establishment delay by 50 ms + T_identify_intra_NR (known FR1 cell: max(200 ms, 5 T_SMTC), Table
+6.2.1.2.1-1) + T_SI-NR + T_PRACH (at most the SSB-to-PRACH association period + 10 ms, TS 38.213
+Table 8.1-1), followed by RRCReestablishment processing of 10 ms (TS 38.331 V19.4.0 Table 12.1-1).
+That is about 0.28 s when the system information is already held and about 1.55 s with the T_SI of
+1280 ms of the test case A.6.3.2.1.1.2. HandoverLab's `reest_s` of 1.0 s lies inside; ns-3 (ideal
+RRC) takes 0.09 s, below both. The recovery time was therefore not changed towards ns-3.
+
+**Fresh held-out check N3 (2.3.0).** One setting was chosen on the light-traffic N2 cells above
+(`protocol.lm_load` 0.15, with `protocol.exec_can_fail` false, as ns-3 has ideal execution) and
+tested on 40 new ns-3 runs (seeds 301-305, ISD 200 / 400 m, 12 / 24 m/s, TTT 100 / 640 ms, light
+traffic), with limits fixed before the runs:
+
+| Check | Limit | Fixed link-monitoring load 0.15 | Default link monitoring |
+|---|---|---|---|
+| Failure level, sum HandoverLab / sum ns-3 | 0.67-1.5 | 0.47, fails | 0.16, fails |
+| Failure order over the 8 cells (Spearman) | at least 0.8 | 0.95, passes | 0.78, fails |
+| Handover rate, median ratio | 0.8-1.25 | 0.93, passes | 0.96, passes |
+| Direction of the TTT effect on failures | 3 of 4 | 4, passes | 4, passes |
+
+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.
 
 **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