handoverlab 2.0.0__tar.gz → 2.2.0__tar.gz

handoverlab-2.2.0/.zenodo.json

@@ -0,0 +1,34 @@
+{
+  "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) for many users in dense 5G-Advanced and beyond-5G networks, on a street grid, in an open area, along a highway, in an indoor office, in 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), 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.",
+  "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"
+  ],
+  "related_identifiers": [
+    {
+      "identifier": "https://github.com/mjs19971997/handoverlab",
+      "relation": "isSupplementTo",
+      "scheme": "url"
+    }
+  ]
+}

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

@@ -7,6 +7,151 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-10-22
+
+### Added
+
+- Fast fading as an option (`radio.fast_fading`: `tdl-a` .. `tdl-e`, off by default): the tapped delay line
+  models of TR 38.901 V19.5.0 clause 7.7.2 with the delay scaling of Eq. 7.7-1 (`radio.delay_spread_ns`, 100 ns
+  by default) and the K-factor change of clause 7.7.6 (`radio.fading_k_db`); each user-cell link fades on its own
+  with 32 sinusoids per Rayleigh tap (Jakes spectrum, f_D from the user's speed) and the LOS tap of TDL-D / -E at
+  0.7 f_D. Link-to-system mapping (`handoverlab.channel.l2s`): radio-link monitoring compares the MIESM effective
+  SINR of QPSK over the 24 PRBs of the hypothetical PDCCH (TS 38.133 Tables 8.1.2.1-1/-2) with Qout / Qin, and
+  the rate uses the capacity-equivalent SINR over the carrier. Base engine only in this version. With the option
+  off every result is unchanged. Guide: `docs/guides/fading.md`; `verify` group `fading` (criteria fixed before
+  the model was written; 32 sinusoids instead of 16 after the Rayleigh test failed with 16).
+- Slot scheduler as an option (`protocol.scheduler`: `rr` or `pf`, off by default): every slot of the interval is
+  played (slot length of TS 38.211 Table 4.3.2-1), the free PRBs of a cell go to its users with data, the MCS is
+  the highest of TS 38.214 Table 5.1.3.1-1 with a block-error probability of at most 10 % at the reported SINR,
+  the TBS follows TS 38.214 clause 5.1.3.2, and HARQ runs with 8 processes per user, chase combining and at most
+  `protocol.harq_max_tx` transmissions after `protocol.harq_rtt_slots`. The block-error probability is the normal
+  approximation of the finite-blocklength error probability on the BICM bit channel of the modulation
+  (`handoverlab.linklevel`), with an implementation loss `protocol.l2s_loss_db`. Base engine only; about 45
+  times slower than the rate model. Guide: `docs/guides/scheduler.md`.
+- `benchmarks/ns3/run_benchmark.py --fading`: the ns-3 runs with ns-3's TR 38.901 fast fading.
+
+### Documentation
+
+- Fast fading against ns-3 runs with fading (96 runs, criterion fixed before the runs): `tdl-c` passes
+  (handover ratio 1.04, unnecessary-handover ratio 1.24, ranks 0.97 / 0.98); `docs/guides/fading.md`.
+- Held-out check of the failure-model parts on 40 new ns-3 runs, limits fixed before the runs: execution time
+  passes; the load effect on link monitoring and the time without connection after a failure fail; execution
+  failures are not measurable (none in ns-3). Reported as is in `docs/calibration.md`.
+
+## [2.1.0] - 2026-10-21
+
+A clause-by-clause audit of the protocol engine against TS 38.331 V18.11.0, TS 38.133, TS 38.300 V18.11.0 and
+TS 38.321, of the value domains against the ASN.1 of TS 38.331, and of the large-scale channel and the scenario
+cards against TR 38.901 V19.5.0, TR 37.885 V15.3.0, TR 38.811 V15.4.0, TR 38.821 V16.2.0 and ITU-R M.2412-0.
+Every change that alters results sits behind a switch: `protocol.rrc_detail: simple` and
+`radio.channel_detail: simple` (both now in `handoverlab.stability.LEGACY_1X`) and the card values of
+`handoverlab.stability.LEGACY_CARDS` give the 2.0.0 model back, and the 1.x golden fingerprints are still
+reproduced. Results of an unchanged configuration differ from 2.0.0 (`MODEL_VERSION` 3; new golden
+fingerprints in `verify/data/golden.json`).
+
+### Added
+
+- `protocol.rrc_detail` (`3gpp`, the default, or `simple`, the engine of 2.0.0). With `3gpp`:
+  - out-of-sync and in-sync indications every max(10 ms, T_SSB) (TS 38.133 8.1.6); N310 counts consecutive
+    out-of-sync indications while T310 is stopped, N311 consecutive in-sync indications while it runs, each reset
+    by the other indication (TS 38.331 clause 7.2, 5.3.10.2), in all three engines and the compiled kernel;
+  - DAPS: T310 of the source keeps running at the reconfiguration with sync (5.3.5.5.2), the source link is
+    monitored during T304 and can fail (5.3.10.1, 5.3.10.3), and the UE falls back to the source only if no
+    source RLF was detected (5.3.5.8.3); no DAPS from FR2 to FR2 (TS 38.300 9.2.3.1) and none for NTN (refused,
+    16.14.3.2.1);
+  - LTM keeps its ltm-Config across a cell switch (5.3.5.18.6) and adds 20 ms of T_LTM-processing on a change of
+    frequency range (TS 38.133 6.3.1.3);
+  - CHO executes when the time-to-trigger of its condition expires, also between measurement instants, like the
+    report of 5.5.4.1 (5.3.5.13.4); CHO with condEventD2 and A3 keeps one state and time-to-trigger per event
+    (`ttt_d2_s`), updated at every measurement and reset on release; a recovery into a prepared cell is a
+    reconfiguration with sync and re-establishes if the cell cannot be joined before T304 expires (5.3.7.3);
+  - L3 filter with the intra-frequency L1 period of the frequency range as reference period (5.5.3.2),
+    Qout_LR = Qout + 4 dB for beam failure detection (TS 38.133 Tables 8.5.2.1-1 and 8.1.2.1-1), the RLM set
+    N_RLM, the BFD timer reset only after it expired, and L1-RSRP with N = 8 in FR2 (9.5.4.1);
+  - the RRC messages counted one by one: measurement reports, commands (an LTM cell switch is a MAC CE),
+    configurations once per user, Complete messages and releases.
+- Outcome `coverage` and metric `coverage_failures_pm`: a failure after which the UE re-establishes in its
+  serving (or target) cell is neither too early nor too late. The outcome classes follow TS 38.300 15.5.2.2.2
+  (too early: re-establishment in the source; wrong cell: in a cell other than source and target; too late: a
+  failure before a handover, re-establishment elsewhere), one class per failure; `too_late_pm` counts the classes.
+- `handoverlab.standard`: the value domains of TS 38.331 V18.11.0 (TimeToTrigger, Hysteresis,
+  MeasTriggerQuantityOffset, Q-OffsetRange, FilterCoefficient, ReportInterval, RLF timers and constants, t304,
+  SSB periodicity, RSRP-Range, maxNrofCondCells, the D2 distance steps) with the clause or page of each, and
+  `check_rule` / `check_scenario`; the `verify` group `values` checks every built-in card and rule default;
+  studies have a gate `standard_values` (blocking by default), and grid extensions stay on standard values.
+- `radio.channel_detail` (`3gpp`, the default, or `simple`): with `3gpp` the place-tied shadowing and LOS
+  fields have the exponential autocorrelation exp(-d / d_cor) of TR 38.901 Eq. (7.4-5) (circulant embedding,
+  periodic with the highway wrap-around), the shadowing is uncorrelated between sites (clause 7.5 step 4),
+  UMa has C'(h_UT) in the LOS probability and the random effective environment height of Table 7.4.1-1
+  note 1 (h_UT >= 13 m), antenna heights outside the applicability ranges of Table 7.4.1-1 are refused,
+  links beyond the upper distance bound give a warning, and a co-sited layer must keep the LOS-state and
+  shadowing settings of the first layer (clause 7.6.5).
+- `radio.pathloss: inh_office_open` (the open-office LOS probability); mobility profiles `p3`, `v30`, `v120`
+  (the fixed speeds of ITU-R M.2412-0 Tables 5a-5c) and `v140c`, `v70c` (TR 37.885 highway speeds on the lane
+  centre); `ntn.hpbw_deg` (unset: the tabled 3 dB beamwidth of TR 38.821 Tables 6.1.1.1-1/-2, from which the
+  beam spacing of Table 6.1.1.1-4 is computed) and `ntn.los_model` (`los`: the baseline "Clear Sky, Line of
+  sight" of TR 38.821 Table 6.1.1.1-5); `handoverlab.stability.LEGACY_CARDS`; the IRR-glass loss as a
+  parameter of the calibration module.
+- `benchmarks/ns3/`: the ns-3 / 5G-LENA side of the comparison as a package anyone can rerun: the A3-only ns-3
+  program of the reference scenario (`handoverlab-ns3-a3.cc`, GPL-2.0-only like ns-3, outside the Python
+  package), `run_benchmark.py` for parts A, B and C (resumable, parallel) and the library state of the
+  reference runs; `handoverlab verify --ns3 --ns3-reference FILE` compares HandoverLab with such a file.
+- "Model boundaries" and "Scope: 5G-Advanced and beyond 5G" in the README, with a test that keeps the table in
+  step with the registered rules, cards and layouts.
+- The page "The 10 ms step" (`docs/time-step.md`): 10, 5, 2 and 1 ms on two scenarios and four procedures, with
+  criteria fixed before the runs; all 30 met, the metrics identical seed by seed.
+- The reference study (`examples/study_reference.yaml`, `docs/reference-study.md`): CHO against A3 at an equal
+  failure budget. The confirmatory question is not answered: the study gates stopped it, as CHO meets the budget
+  at every setting up to 8 dB and 960 ms; an exploratory test stage shows the price (-90 % unnecessary
+  handovers, but 12 dB lower SINR and 25 % lower throughput).
+
+### Changed
+
+- `radio.shadow_site_corr` is unset by default (0 with `channel_detail: 3gpp`, 0.5 with `simple`).
+- Cards: UE antenna 1.6 m (TR 37.885 vehicle type 2) on `smoke`, `urban-grid-10ghz`, `fr3-urban-15ghz`,
+  `urban-grid-28ghz-beams`; `indoor-office-4ghz` with `p3` and the open-office LOS probability;
+  `rural-700mhz` with `v120`; `dense-urban-2layer` with `v30`; highway cards with `v140c`; `ntn-leo600-2ghz`
+  with `ntn.los_model: los`. The card pages leave out keys that the layout and radio model do not read, keep
+  the card's own source for beam keys, and the cards state the remaining abstractions (one shadowing
+  decorrelation distance, LOS and NLOS on one shadowing realisation, LOS state on top of the buildings, user
+  numbers, scintillation as a link-budget margin, no wrap-around beam tiers).
+- `verify`: radio statistics expect the exponential correlation and no correlation between sites; highway
+  check H3 uses the uncorrelated shadowing of TR 38.901 and simulates it along each vehicle's path (the
+  place-tied exponential field leaves too few independent samples per road), H2 accepts a jump at the
+  wrap-around up to the size of the ordinary steps (the radio map has a whole number of pixels per period);
+  NTN check N2 checks the tabled beamwidth (it passes now for both S-band apertures).
+- `a3_mro`: `step_db` 1 dB by default (0.5 dB before), so that every offset is a Q-OffsetRange value; a
+  ping-pong must be strictly shorter than `pingpong_s`, and no ping-pong is counted across a re-establishment.
+- Validation: `ssb_avg` at most min(`n_ssb`, 16) (maxNrofSS-BlocksToAverage); FR2-2 power classes 1 to 3;
+  T310, delays and the report interval must not be negative; with `rrc_detail: 3gpp` and TS 38.133 measurement
+  periods on several carriers, `protocol.gap_pattern` must be one of the per-UE gap ids that TS 38.133 Table
+  9.1.2-3 allows for the frequency ranges (FR1 present: 0-11, 24, 25; FR2 only: 12-25).
+- Energy: each cell counts with the transmit power of its own layer (2.0.0: the base layer's power for every
+  cell), the metric is per cell, and the EARTH model has the number of transceivers of Auer et al. 2011 Eq. 1
+  (`radio.energy_ntrx`, 2 for the micro base station of Table 2; 1.x and 2.0.0: 1, now in `LEGACY_1X`).
+- SS-RSRP per resource element with beams or layers: the power is spread over the 12 N_RB subcarriers of
+  TS 38.101-1 / TS 38.101-2 Table 5.3.2-1 (`radio.channel_detail: 3gpp`; 2.0.0: B / SCS, guard bands included).
+- The title is "System-level handover simulator for 5G-Advanced and beyond-5G research" (README, PyPI, CITATION,
+  Zenodo, documentation site).
+
+### Fixed
+
+- Citations checked against the text of each document: FTP model 3 is defined in TR 36.872 Annex A.1 with the
+  0.5 Mbyte files of TR 38.802 Table A.2.1-1 and TR 38.821 Table 6.1.1.1-7 (TR 36.814 has models 1 and 2 only);
+  `protocol.reest_s` (1 s) is an assumption: TS 38.133 6.2.1.2.1 bounds the re-establishment delay by 50 ms +
+  cell identification (Table 6.2.1.2.1-1) + system information + PRACH, and TR 36.842 Table E.1-2 uses 250 ms;
+  MRO cites TS 28.313 clause 7.1.2; hand-calculated radio checks use c = 3e8 m/s; rows of
+  `docs/standard-compliance.md`, the user guide and the guides rewritten where the text said otherwise.
+- Every citation of TS 38.133, TS 38.300, TS 38.321, TS 38.213 and TS 38.215 checked against the V19 texts (and
+  the versions named): no DAPS from FR2 to FR2 is TS 38.300 9.2.3.1 (not 9.2.3.2); recovery into a CHO candidate
+  9.2.3.1 and 9.2.7 (not 9.2.3.4); M_meas_period_w/o_gaps TS 38.133 9.2.5.1; the BFD threshold in the user
+  guide is Qout_LR; the restart of link monitoring on a new cell is called what it is, an interpretation of
+  TS 38.133 8.1.2.2; the SSB as BFD reference signal cites TS 38.133 8.5.1; conditional LTM cites TS 38.300
+  V19.4.0 9.2.3.7.
+- The verify check of the configured LTM / DAPS interruption (V1e) runs with ideal random access, so that an
+  execution waiting for its target under T304 does not count against it; the README table of model boundaries is
+  checked against the built-in rules only.
+
 ## [2.0.0] - 2026-10-20
 
 2.0.0 makes the 3GPP values the defaults. Results of an unchanged configuration therefore differ from 1.x;
@@ -789,7 +934,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.0.0...HEAD
+[Unreleased]: https://github.com/mjs19971997/handoverlab/compare/v2.2.0...HEAD
+[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
 [1.12.0]: https://github.com/mjs19971997/handoverlab/compare/v1.11.0...v1.12.0
 [1.11.0]: https://github.com/mjs19971997/handoverlab/compare/v1.10.0...v1.11.0

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

@@ -1,6 +1,6 @@
 cff-version: 1.2.0
 message: "If you use this software, please cite it as below."
-title: "HandoverLab: system-level simulation of handover and mobility beyond 5G"
+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
@@ -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.0.0"
+version: "2.2.0"
 doi: 10.5281/zenodo.23409131
 identifiers:
   - type: doi
@@ -23,7 +23,7 @@ identifiers:
   - type: doi
     value: 10.5281/zenodo.23409402
     description: "Version 1.0.1 on Zenodo"
-date-released: 2026-10-20
+date-released: 2026-10-22
 license: MIT
 repository-code: "https://github.com/mjs19971997/handoverlab"
 url: "https://mjs19971997.github.io/handoverlab/"

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: handoverlab
-Version: 2.0.0
-Summary: System-level simulator of handover and mobility procedures in dense 5G and beyond-5G networks
+Version: 2.2.0
+Summary: System-level handover simulator for 5G-Advanced and beyond-5G research
 Author: Mostafa Jalili Sanjarani, Yasser Elmi Sola
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/mjs19971997/handoverlab
@@ -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 simulator for studying handover in dense 5G and beyond-5G networks, written in Python.
+A system-level handover simulator for 5G-Advanced and beyond-5G research, 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
@@ -75,7 +75,8 @@ outcome label for every handover attempt.
 > 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,
 > the urban vehicles of TR 37.885, the path-loss constants of TR 38.901), so results differ from 1.x;
-> one switch, `LEGACY_1X`, gives every 1.x result back bit for bit
+> one switch, `LEGACY_1X`, gives every 1.x result back bit for bit (for the cards changed since 2.1.0
+> together with their old values in `LEGACY_CARDS`)
 > ([moving from 1.x to 2.0](https://github.com/mjs19971997/handoverlab/blob/main/docs/migration-2.0.md)).
 
 ## See it
@@ -157,7 +158,7 @@ event D2 of Release 18:
   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.
 - **Traffic**: constant service rates per 5QI class, or a traffic model per user: full buffer,
-  periodic packets (as VoIP) or FTP model 3 of TR 36.814. The load of every cell, and so the
+  periodic packets (as VoIP) or FTP model 3 (TR 38.802, the 0.5 Mbyte files of TR 38.821). The load of every cell, and so the
   interference, follows the traffic of its users.
 - **Measurements**: L1 samples, the TS 38.331 L3 filter, Event A3 with time-to-trigger, periodic
   reporting for conditional handover.
@@ -169,9 +170,9 @@ 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 (TR 36.839 / TR 36.842 values by default), the handover command
-  during T310 and the restart of the link monitoring on a new cell as TS 38.331 and TS 38.133 specify
-  (defaults since 2.0.0), with options for the link monitoring (own interferer load, ideal random access).
+  execution failures, re-establishment after a fixed outage (1 s, an assumption), 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,
   censored), failures by cause, ping-pong, preparation overhead, interruption, delivered rate,
   signalling (RRC messages, commands), L1 measurements of the device and network energy (EARTH
@@ -180,17 +181,47 @@ event D2 of Release 18:
   engine draws no random numbers; golden event-log fingerprints guard every change. An optional
   compiled kernel (`run.backend: numba`) gives the same event logs bit for bit.
 
-## Built for beyond-5G
-
-HandoverLab targets the questions of dense beyond-5G networks: small cells 50-300 m apart, the
-upper mid-band (FR3, 7-24 GHz; the scenario `fr3-urban-15ghz`, 10 GHz by default), and the
-mobility procedures beyond baseline handover: conditional handover, DAPS handover,
-L1/L2-triggered mobility of Release 18 and conditional LTM from the Release 19 work, satellite access
-with the conditional handover events of Release 18 (non-terrestrial networks, since 2.0.0), next to rules
-that learn from handover outcomes and
-A3 tuned by mobility robustness optimisation, the fair baseline for a new rule. The cost
-of each procedure (signalling, prepared cells, interruption, energy) is measured next to its
-benefit.
+## Model boundaries
+
+What HandoverLab is for, at a glance: questions about handover and mobility procedures and the rules that
+drive them, compared on the same worlds. What it abstracts or leaves out decides which conclusions it supports;
+the clause-by-clause detail is in [standard compliance](https://github.com/mjs19971997/handoverlab/blob/main/docs/standard-compliance.md).
+
+| 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 |
+| 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 |
+| 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.
+
+## Scope: 5G-Advanced and beyond 5G
+
+HandoverLab is a system-level handover simulator for 5G-Advanced and beyond-5G research. It covers the
+mobility procedures of Releases 16 to 19 (conditional handover, DAPS handover, L1/L2-triggered mobility,
+conditional LTM, conditional handover with the location events of Release 18 for satellites) in dense
+networks with small cells 50-300 m apart. Three paths lead beyond 5G:
+
+- **The upper mid-band (FR3, 7-24 GHz)**, studied in TR 38.901 V19.5.0: the card `fr3-urban-15ghz` and every
+  layout at any carrier the path-loss models cover.
+- **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.
+
+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
+rule yet. HandoverLab therefore claims no 6G procedure; the paths above are where 6G mobility work is expected
+to build on 5G-Advanced. The cost of every procedure (signalling, prepared cells, interruption, energy) is
+measured next to its benefit.
 
 ## Calibrated against 3GPP
 
@@ -211,7 +242,9 @@ Every rule of the handover procedure is listed clause by clause against the offi
 [standard compliance](https://github.com/mjs19971997/handoverlab/blob/main/docs/standard-compliance.md),
 with what is followed, what is abstracted and what is not modelled yet. The 3GPP protocol profile of
 1.9.0 (`protocol: {cmd_during_t310: receive, t304_s: 1.0, rlm_holdoff_s: 0.2}`), the default since 2.0.0,
-makes the handover command and its execution behave as TS 38.331 specifies. Against handover statistics
+makes the handover command and its execution follow TS 38.331; the audit of 2.1.0 checked every procedure,
+requirement and value against TS 38.331 V18.11.0, TS 38.133, TS 38.300 and the TRs, and what remains an
+abstraction is listed on that page. Against handover statistics
 measured in commercial 5G networks (SIGCOMM, IMC and MobiCom measurement studies) the profile
 brings the handover failure rate from about six times above the measured range to just above it;
 ping-pong with the Verizon A3 setting and the handover distance in low-band rural cells match.
@@ -221,8 +254,8 @@ the DAPS and LTM interruptions are checked against TS 38.133 and published 3GPP
 ## Checked against ns-3
 
 The same 24 Event-A3 settings were simulated in HandoverLab and in the packet-level simulator
-ns-3 with 5G-LENA. Handover and unnecessary-handover rates agree (median ratio 0.92, rank
-correlation 0.99). For failure rates, with the in-car loss of ns-3 and the restart of the link
+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
@@ -277,7 +310,7 @@ L1/L2-triggered mobility.
 - **1.4.0**: traffic models per user (`traffic.model`: full buffer, periodic, FTP model 3); a
   dashboard with confidence intervals, a map of where handovers and failures happen, and the status
   of a running study; the ns-3 link-monitoring finding in the calibration report.
-- **1.3.0**: optional restart of the link monitoring on a newly joined cell (TS 38.133).
+- **1.3.0**: optional restart of the link monitoring on a newly joined cell (an interpretation of TS 38.133 8.1.2.2).
 - **1.2.0**: optional penetration loss per user; the ns-3 comparison with the in-car loss of ns-3.
 - **1.1.0 / 1.1.1**: optional link-monitoring model; held-back ns-3 results; issue forms, CI on
   Windows for every test.

{handoverlab-2.0.0 → handoverlab-2.2.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 simulator for studying handover in dense 5G and beyond-5G networks, written in Python.
+A system-level handover simulator for 5G-Advanced and beyond-5G research, 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
@@ -17,7 +17,8 @@ outcome label for every handover attempt.
 > 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,
 > the urban vehicles of TR 37.885, the path-loss constants of TR 38.901), so results differ from 1.x;
-> one switch, `LEGACY_1X`, gives every 1.x result back bit for bit
+> one switch, `LEGACY_1X`, gives every 1.x result back bit for bit (for the cards changed since 2.1.0
+> together with their old values in `LEGACY_CARDS`)
 > ([moving from 1.x to 2.0](https://github.com/mjs19971997/handoverlab/blob/main/docs/migration-2.0.md)).
 
 ## See it
@@ -99,7 +100,7 @@ event D2 of Release 18:
   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.
 - **Traffic**: constant service rates per 5QI class, or a traffic model per user: full buffer,
-  periodic packets (as VoIP) or FTP model 3 of TR 36.814. The load of every cell, and so the
+  periodic packets (as VoIP) or FTP model 3 (TR 38.802, the 0.5 Mbyte files of TR 38.821). The load of every cell, and so the
   interference, follows the traffic of its users.
 - **Measurements**: L1 samples, the TS 38.331 L3 filter, Event A3 with time-to-trigger, periodic
   reporting for conditional handover.
@@ -111,9 +112,9 @@ 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 (TR 36.839 / TR 36.842 values by default), the handover command
-  during T310 and the restart of the link monitoring on a new cell as TS 38.331 and TS 38.133 specify
-  (defaults since 2.0.0), with options for the link monitoring (own interferer load, ideal random access).
+  execution failures, re-establishment after a fixed outage (1 s, an assumption), 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,
   censored), failures by cause, ping-pong, preparation overhead, interruption, delivered rate,
   signalling (RRC messages, commands), L1 measurements of the device and network energy (EARTH
@@ -122,17 +123,47 @@ event D2 of Release 18:
   engine draws no random numbers; golden event-log fingerprints guard every change. An optional
   compiled kernel (`run.backend: numba`) gives the same event logs bit for bit.
 
-## Built for beyond-5G
-
-HandoverLab targets the questions of dense beyond-5G networks: small cells 50-300 m apart, the
-upper mid-band (FR3, 7-24 GHz; the scenario `fr3-urban-15ghz`, 10 GHz by default), and the
-mobility procedures beyond baseline handover: conditional handover, DAPS handover,
-L1/L2-triggered mobility of Release 18 and conditional LTM from the Release 19 work, satellite access
-with the conditional handover events of Release 18 (non-terrestrial networks, since 2.0.0), next to rules
-that learn from handover outcomes and
-A3 tuned by mobility robustness optimisation, the fair baseline for a new rule. The cost
-of each procedure (signalling, prepared cells, interruption, energy) is measured next to its
-benefit.
+## Model boundaries
+
+What HandoverLab is for, at a glance: questions about handover and mobility procedures and the rules that
+drive them, compared on the same worlds. What it abstracts or leaves out decides which conclusions it supports;
+the clause-by-clause detail is in [standard compliance](https://github.com/mjs19971997/handoverlab/blob/main/docs/standard-compliance.md).
+
+| 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 |
+| 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 |
+| 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.
+
+## Scope: 5G-Advanced and beyond 5G
+
+HandoverLab is a system-level handover simulator for 5G-Advanced and beyond-5G research. It covers the
+mobility procedures of Releases 16 to 19 (conditional handover, DAPS handover, L1/L2-triggered mobility,
+conditional LTM, conditional handover with the location events of Release 18 for satellites) in dense
+networks with small cells 50-300 m apart. Three paths lead beyond 5G:
+
+- **The upper mid-band (FR3, 7-24 GHz)**, studied in TR 38.901 V19.5.0: the card `fr3-urban-15ghz` and every
+  layout at any carrier the path-loss models cover.
+- **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.
+
+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
+rule yet. HandoverLab therefore claims no 6G procedure; the paths above are where 6G mobility work is expected
+to build on 5G-Advanced. The cost of every procedure (signalling, prepared cells, interruption, energy) is
+measured next to its benefit.
 
 ## Calibrated against 3GPP
 
@@ -153,7 +184,9 @@ Every rule of the handover procedure is listed clause by clause against the offi
 [standard compliance](https://github.com/mjs19971997/handoverlab/blob/main/docs/standard-compliance.md),
 with what is followed, what is abstracted and what is not modelled yet. The 3GPP protocol profile of
 1.9.0 (`protocol: {cmd_during_t310: receive, t304_s: 1.0, rlm_holdoff_s: 0.2}`), the default since 2.0.0,
-makes the handover command and its execution behave as TS 38.331 specifies. Against handover statistics
+makes the handover command and its execution follow TS 38.331; the audit of 2.1.0 checked every procedure,
+requirement and value against TS 38.331 V18.11.0, TS 38.133, TS 38.300 and the TRs, and what remains an
+abstraction is listed on that page. Against handover statistics
 measured in commercial 5G networks (SIGCOMM, IMC and MobiCom measurement studies) the profile
 brings the handover failure rate from about six times above the measured range to just above it;
 ping-pong with the Verizon A3 setting and the handover distance in low-band rural cells match.
@@ -163,8 +196,8 @@ the DAPS and LTM interruptions are checked against TS 38.133 and published 3GPP
 ## Checked against ns-3
 
 The same 24 Event-A3 settings were simulated in HandoverLab and in the packet-level simulator
-ns-3 with 5G-LENA. Handover and unnecessary-handover rates agree (median ratio 0.92, rank
-correlation 0.99). For failure rates, with the in-car loss of ns-3 and the restart of the link
+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
@@ -219,7 +252,7 @@ L1/L2-triggered mobility.
 - **1.4.0**: traffic models per user (`traffic.model`: full buffer, periodic, FTP model 3); a
   dashboard with confidence intervals, a map of where handovers and failures happen, and the status
   of a running study; the ns-3 link-monitoring finding in the calibration report.
-- **1.3.0**: optional restart of the link monitoring on a newly joined cell (TS 38.133).
+- **1.3.0**: optional restart of the link monitoring on a newly joined cell (an interpretation of TS 38.133 8.1.2.2).
 - **1.2.0**: optional penetration loss per user; the ns-3 comparison with the in-car loss of ns-3.
 - **1.1.0 / 1.1.1**: optional link-monitoring model; held-back ns-3 results; issue forms, CI on
   Windows for every test.

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

@@ -10,6 +10,16 @@ range, and none is more than about 1 dB from the industry mean. `handoverlab ver
 check (group `calibration`). With c = 3.0e8 m/s in the breakpoint distances (2.0.0) every number of this
 page is unchanged.
 
+**Version.** The drop uses the formulas of TR 38.901 V19.5.0 with one exception: the IRR-glass loss of the
+high-loss O2I model. V19.5.0 Table 7.4.3-1 gives 25.4 + 0.11 f dB (note 2: updated in the Release 19 study
+on 7-24 GHz); the calibration keeps the earlier 23 + 0.3 f dB of TR 38.901 V17.0.0, because the companies of
+R1-165974 worked before that change (`IRR_GLASS_R1_165974` in `handoverlab.verify.calibration`; pass
+`irr_glass=IRR_GLASS_V19` to `simulate_drops` for the V19.5.0 value). With the V19.5.0 value (30 000 users,
+seed 1) the 6 GHz cases stay inside the company range, but at 30 GHz the coupling loss and the SINR of UMa
+and UMi leave it (coupling loss: UMa 15 of 19 percentiles inside, largest distance from the mean 3.30 dB;
+UMi 11 of 19, 3.25 dB): the higher glass loss at 30 GHz is a change of the model, not an error of the
+reproduction.
+
 ![HandoverLab against the 21 companies of 3GPP R1-165974](images/calibration_38901.png)
 
 ## The reference
@@ -34,10 +44,10 @@ of the simulator (a test checks that they give exactly the values of `handoverla
 | Layout | UMa: 19 sites, ISD 500 m, BS 25 m; UMi: 19 sites, ISD 200 m, BS 10 m; geographical wrap-around | TR 38.901 Tables 7.2-1 and 7.8-1 |
 | Indoor office | 12 ceiling sites, 20 m apart, in a 120 m x 50 m hall, BS 3 m, users 1 m | Table 7.2-2, Figure 7.2-1 |
 | Sectors and antenna | 3 sectors per site (30, 150, 270 deg); element pattern of Table 7.3-1 (8 dBi); 10 vertical elements, d_V = lambda / 2, DFT tilt 102 deg (UMa, UMi), 110 deg (indoor) | Tables 7.3-1, 7.8-1; Eq. 7.3-1 |
-| Users | uniform; UMa and UMi 80 % indoor at height 3 (n_fl - 1) + 1.5 m, n_fl ~ uniform(1, N_fl), N_fl ~ uniform(4, 8); minimum 2D distance 35 m (UMa), 10 m (UMi), applied to d2D-out | Table 7.2-1; TR 36.873 Table 6-1 |
+| Users | uniform; UMa and UMi 80 % indoor at height 3 (n_fl - 1) + 1.5 m, n_fl ~ uniform(1, N_fl), N_fl ~ uniform(4, 8); minimum 2D distance 35 m (UMa), 10 m (UMi), applied to d2D-out | Table 7.2-1 ("Same as 3D-UMa in TR36.873"); the formula as in ITU-R M.2412-0 Table 5b (TR 36.873 itself is not in the local sources) |
 | Path loss and LOS | Table 7.4.1-1 (UMa with the random effective environment height of note 1), Table 7.4.2-1 (UMa with C'(h_UT), indoor open office) | TR 38.901 |
 | Shadowing | LOS / NLOS of Table 7.4.1-1; 7 dB for indoor users of UMa and UMi; independent between sites, shared by the sectors of a site | Tables 7.4.1-1 and 7.5-6 |
-| O2I loss | 50 % low loss, 50 % high loss; d2D-in = min of two uniform(0, 25 m) | clause 7.4.3.1, Table 7.4.3-2 |
+| O2I loss | 50 % low loss, 50 % high loss; d2D-in = min of two uniform(0, 25 m); IRR glass 23 + 0.3 f dB (see Version above) | clause 7.4.3.1, Tables 7.4.3-1 (V17.0.0 value), 7.4.3-2 |
 | Link budget | 49 dBm (UMa), 44 dBm (UMi) at 6 GHz with 20 MHz; 35 dBm at 30 GHz with 100 MHz; 24 dBm indoor; UT noise figure 9 dB; isotropic UT | Table 7.8-1 |
 | Association | sector with the highest received power (handover margin 0 dB), no fast fading | Table 7.8-1 |
 

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

@@ -10,6 +10,24 @@ rates agree (median ratios 0.93 and 0.95, ranks 0.97), and the failure level agr
 0.84, limit 0.67-1.5), but the order of the failure rates does not (rank 0.68, limit 0.8). See
 [standard compliance](standard-compliance.md#fresh-ns-3-hold-out-190).
 
+**Held-out check of the failure-model parts (2.2.0).** 40 new ns-3 runs (seeds 201-210, urban,
+20 users, A3 3 dB / 300 ms, ISD 200 and 400 m at 16 m/s, light traffic and 12 Mbit/s full traffic)
+tested each part of the failure model against limits fixed before the runs, with the 2.0.0 engine as
+registered (2.1.0 defaults gave the same verdicts):
+
+| Part | ns-3 | HandoverLab | Limit | Result |
+|---|---|---|---|---|
+| Load: link-monitoring SINR, light to full traffic | -2.1 / -1.8 dB | -13.3 / -13.4 dB | within 2 dB | fails |
+| Execution: command to completion | median 4.1 ms | `exec_s` 10 ms | within 10 ms | passes |
+| 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.
+
 **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
 hold-out sets when the in-car loss of ns-3 and the restart of link monitoring are switched on
@@ -20,7 +38,7 @@ and diagnosis runs:
 |---|---|---|---|
 | In-car penetration loss | added only at 30-120 km/h | TR 38.901 7.4.3.2: a property of a user in a car | per user when configured, any speed (`radio.penetration_db`) |
 | Time to detect out-of-sync | 20 frames of 10 control receptions; 0.65-0.83 s at light traffic | TS 38.133 8.1: about 200 ms | evaluated over time (`protocol.qout_window_s` 0.2 s) |
-| Link monitoring on a new cell | restarts | TS 38.331: T310 stops at a handover; out-of-sync is evaluated anew (TS 38.133 8.1) | option since 1.3.0 (`protocol.rlm_holdoff_s`) |
+| Link monitoring on a new cell | restarts | TS 38.331: T310 stops at a handover; out-of-sync evaluated anew (an interpretation of TS 38.133 8.1.2.2: quality over the last T_Evaluate_out) | option since 1.3.0 (`protocol.rlm_holdoff_s`) |
 
 On the first two, HandoverLab is closer to the 3GPP texts; on the third, ns-3 was, and HandoverLab
 now offers it. The sections below give the evidence in the order it was found.
@@ -268,8 +286,9 @@ reference includes this loss.
 The remaining failures were compared with those of ns-3, failure by failure (A3 6 dB / 100 ms at
 200 m). At 42 m/s, every HandoverLab failure came about 0.2 s after a handover, at an
 intersection: T310 had started on the newly joined cell at once, and the next handover command
-arrived while it was running. In ns-3, as in TS 38.133 clause 8.1, radio-link monitoring restarts
-on a new cell and needs a full evaluation period (200 ms) before an out-of-sync indication. Overall,
+arrived while it was running. In ns-3 radio-link monitoring restarts on a new cell and needs a full evaluation period (200 ms)
+before an out-of-sync indication; HandoverLab reads TS 38.133 8.1.2.2 (quality estimated over the last
+T_Evaluate_out) the same way, an interpretation, as no clause defines a restart. Overall,
 half of HandoverLab's failures came less than 2 s after the previous handover, against a quarter to
 a third in ns-3.
 

{handoverlab-2.0.0 → handoverlab-2.2.0}/docs/guides/beams-layers.md

@@ -35,7 +35,8 @@ What happens in a run:
    periodic L1-RSRP reports (`report_s`, `switch_db`, `tci_delay_s`). In FR2 the L1-RSRP period of
    TS 38.133 includes the receive-beam sweeping factor N = 8, so the beam follows a fast user late.
 3. If the serving beam's quality, averaged over the beam-failure-detection period (FR2: 800 ms at a
-   20 ms SSB period), is below Qout, the UE counts beam failure instances; `bfi_max` of them within
+   20 ms SSB period), is below Qout_LR (since 2.1.0 4 dB above Qout, as TS 38.133 Tables 8.5.2.1-1 and
+   8.1.2.1-1 define the two hypothetical PDCCH at 0 dB and +4 dB), the UE counts beam failure instances; `bfi_max` of them within
    the detection timer start beam failure recovery by random access on the best candidate beam.
    A recovery whose random access fails `preamble_max` times is a radio-link failure.
 4. The new metrics `beam_switches_pm`, `beam_failures_pm`, `beam_recoveries_pm`,
@@ -81,7 +82,9 @@ rules:
 ```
 
 - Each layer has its own sites (or `cosited: true`: the sites, LOS states and shadowing of the
-  first layer, TR 38.901 7.6.5). Only cells of one carrier interfere with each other.
+  first layer, TR 38.901 7.6.5; since 2.1.0 such a layer cannot set its own `pathloss`, `los_corr_m` or
+  `shadow_decorr_m` unless `radio.channel_detail` is `simple`). Only cells of one carrier interfere with
+  each other.
 - With `meas_periods: ts38133` the UE measures the other carrier only in the measurement gaps
   (`gap_pattern`, default 6 ms every 40 ms) with the inter-frequency periods of TS 38.133 9.3.5:
   320 ms for an FR1 carrier and 1.6 s for an FR2 carrier. During a gap it receives no data