handoverlab 2.1.0__tar.gz → 2.2.0__tar.gz

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

@@ -7,6 +7,37 @@ 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
@@ -903,7 +934,8 @@ First alpha release (stage 1: the core simulator).
 - Documentation: README, user guide, contribution guide, citation file; CI on Linux, Windows and
   macOS with Python 3.9-3.12.
 
-[Unreleased]: https://github.com/mjs19971997/handoverlab/compare/v2.1.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

{handoverlab-2.1.0 → handoverlab-2.2.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.1.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-21
+date-released: 2026-10-22
 license: MIT
 repository-code: "https://github.com/mjs19971997/handoverlab"
 url: "https://mjs19971997.github.io/handoverlab/"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: handoverlab
-Version: 2.1.0
+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
@@ -190,7 +190,7 @@ 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; a slow time-varying component instead of fast fading | fast fading (clauses 7.5, 7.7), Doppler, small-scale spreads |
+| 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 |

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

@@ -132,7 +132,7 @@ 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; a slow time-varying component instead of fast fading | fast fading (clauses 7.5, 7.7), Doppler, small-scale spreads |
+| 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 |

{handoverlab-2.1.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

handoverlab-2.2.0/docs/guides/fading.md

@@ -0,0 +1,78 @@
+# Fast fading and effective SINR
+
+By default HandoverLab works on the received-power level: path loss, LOS state, shadowing and a
+slow time-varying component, with radio-link monitoring on the wideband SINR. Since 2.2.0 the option
+`radio.fast_fading` adds the fast fading of the tapped delay line (TDL) models of TR 38.901 and maps
+the SINR at several frequencies to one effective SINR. It is off by default; with it off every
+result of 2.1.0 is unchanged bit for bit.
+
+```yaml
+scenario:
+  base: ns3-urban-3.5ghz
+  radio:
+    fast_fading: tdl-c        # tdl-a, tdl-b, tdl-c (NLOS), tdl-d, tdl-e (LOS); null: off
+    delay_spread_ns: 100      # RMS delay spread (TR 38.901 Table 7.7.3-1: 10, 30, 100, 300, 1000 ns)
+    fading_k_db: null         # tdl-d / tdl-e only: another K-factor (TR 38.901 clause 7.7.6)
+```
+
+## 1. The channel
+
+| Item | TR 38.901 V19.5.0 | HandoverLab |
+|---|---|---|
+| Tap delays and powers | Tables 7.7.2-1 to 7.7.2-5 | the five tables, the powers normalised to a unit sum (mean link gain 1) |
+| Delay scaling | Eq. 7.7-1: tau_scaled = tau_model x DS | `delay_spread_ns` |
+| Doppler | clause 7.7.2: Jakes spectrum per tap, f_D = \|v\| / lambda_0 | 32 sinusoids per Rayleigh tap with random arrival angles and phases, f_D from the user's speed and the carrier |
+| LOS tap of TDL-D / TDL-E | Rice, K1 = 13.3 dB / 22 dB, Doppler peak at f_S = 0.7 f_D | a specular component at 0.7 f_D next to the Rayleigh part of the first tap |
+| Another K-factor | clause 7.7.6, Eq. 7.7.6-1 and 7.7.6-2, delays re-normalised | `fading_k_db` (the K of Eq. 7.7.6-2: the LOS power over all Rayleigh taps; about 9 dB for the table of TDL-D) |
+
+Every user-cell link fades independently (the TDL models are single-link models; their MIMO
+extensions of clause 7.7.5 are not used). The channel is evaluated at four points spread over the
+24 PRBs of the hypothetical PDCCH (TS 38.133 Tables 8.1.2.1-1/-2) and at eight points spread over
+the carrier (N_RB of TS 38.101-1/-2 Table 5.3.2-1). The received power of a cell (L1 samples, the
+link budget of every check) takes the mean gain over the PDCCH band, close to the 20 PRBs of an SSB.
+
+## 2. From SINR to one effective SINR
+
+| Use | Mapping | Why |
+|---|---|---|
+| Radio-link monitoring (Qout, Qin) | MIESM for QPSK over the PDCCH band: the mean bit-wise mutual information of QPSK (binary input, Gaussian channel) mapped back to the SINR with the same mutual information on a flat channel | TS 38.133 8.1 defines Qout and Qin as the BLER of a hypothetical QPSK PDCCH; the thresholds `qout_db` / `qin_db` are flat-channel SINRs, so the faded channel is compared through its flat-channel equivalent |
+| Delivered rate | capacity-equivalent SINR over the carrier: 2^(mean log2(1 + SINR)) - 1 | the rate model uses log2(1 + SINR) |
+
+Both mappings return the SINR itself on a flat channel and never more than the mean SINR. Every
+interfering link has its own fading. Above about 18 dB the mutual information of QPSK is 1 to
+double precision; the MIESM result is capped there, far above Qout and Qin. No BLER table of
+another simulator is used; a BLER per MCS (TS 38.214 tables) follows with the slot scheduler.
+
+## 3. Cost and limits
+
+- A single run is about twice as long (32 sinusoids per tap, every step; 10 users on the ns-3 card:
+  about 6 s instead of 3 s for 20 s simulated); many rules on one world take longer (24 rules: about
+  6 to 8 times), as the batched and compiled loops are not used with fading.
+- This version needs the base engine: no beams, layers, NTN or TS 38.133 periods
+  (`meas_periods: sample`, `rlm_eval: fixed`); such a configuration is refused.
+- The step stays 10 ms. At 30 m/s and 3.5 GHz the coherence time is about 1 ms, so successive
+  steps see nearly independent fading; the L1 sample of a measurement instant is one such snapshot.
+
+## 4. Against ns-3 (exploratory)
+
+On the ns-3 card (24 A3 settings, four conditions, one seed) against the stored ns-3 results, which were run
+without fading: with `tdl-c` the median handover ratio is 1.01 and the unnecessary-handover ratio 1.18 (0.95 and
+1.06 without fading), the rank correlations 0.98; the failure rate stays at about 0.01-0.02 per UE-minute
+against 0.43 in ns-3. Fast fading therefore does not close the known gap in failures, which follows the 14 dB gap
+in mean serving SINR (see [verification](../verification.md)).
+
+Against ns-3 runs that use fading themselves (`benchmarks/ns3/run_benchmark.py --fading`, 96 runs, TR 38.901
+fast fading in ns-3), with the criterion fixed before those runs existed (`tdl-c`, delay spread 100 ns, seed
+500; median ratios in [0.8, 1.25], rank correlations at least 0.9): the handover ratio is 1.04 and the
+unnecessary-handover ratio 1.24, close to its limit, and the rank correlations are 0.97 and 0.98, so the
+criterion passes. As additional rows, `tdl-a` would miss the unnecessary-handover limit (1.27), `tdl-d` (1.00 /
+1.16) and no fading (0.98 / 1.09) pass. ns-3 itself moves little with fading (mean failure rate 0.40 against
+0.43 without, serving SINR 11.5 dB in both), and the failure gap stays as it was (HandoverLab 0.014 per
+UE-minute with `tdl-c`).
+
+## 5. Checks
+
+`handoverlab verify --only fading` runs the criteria fixed before the model was written: Rayleigh
+taps with unit power (KS test), the J0 time correlation, the K-factor of the first TDL-D tap, the
+delay spread after scaling, and the two properties of the mappings. `tests/test_fading.py` also
+checks that the option off changes no fingerprint and that a run with fading is reproducible.

handoverlab-2.2.0/docs/guides/scheduler.md

@@ -0,0 +1,65 @@
+# Slot scheduler, MCS and HARQ
+
+By default HandoverLab computes the delivered rate from the SINR with a capacity formula and shares
+a cell's resources among its users in proportion to their demand. Since 2.2.0 the option
+`protocol.scheduler` replaces this with a data plane that plays every slot: resource blocks per
+user, an MCS of TS 38.214, transport blocks that fail with a block error probability, and HARQ
+retransmissions. It is off by default; with it off every result of 2.1.0 is unchanged bit for bit.
+
+```yaml
+scenario:
+  base: ns3-urban-3.5ghz
+  traffic: {model: full_buffer}
+  protocol:
+    scheduler: pf          # rr (round robin) or pf (proportional fair); null: off
+    harq_max_tx: 4         # transmissions of a transport block (first + retransmissions)
+    harq_rtt_slots: 8      # HARQ round trip [slots]
+    l2s_loss_db: 1.0       # implementation loss of the block-error model [dB]
+```
+
+It combines with fast fading (`radio.fast_fading`, see [fast fading](fading.md)): the scheduler
+then uses the effective SINR over the carrier.
+
+## 1. What a slot does
+
+| Item | Source | HandoverLab |
+|---|---|---|
+| Slot length | TS 38.211 Table 4.3.2-1 (2^mu slots per 1 ms subframe) | 1 ms / 2^mu for the subcarrier spacing of the carrier |
+| Resource blocks of a cell | TS 38.101-1/-2 Table 5.3.2-1 | N_RB of the carrier, less the share of the background load |
+| Who gets them | gNB implementation (not specified) | `rr`: every connected user with data gets an equal share in every slot; `pf`: the whole band goes to the user with the largest instantaneous over average rate; a due retransmission comes first |
+| MCS | TS 38.214 Table 5.1.3.1-1 (MCS table 1) | the highest MCS whose block-error probability at the SINR reported one measurement interval earlier is at most 10 % |
+| Transport block size | TS 38.214 clause 5.1.3.2 | steps 1 to 4 with Table 5.1.3.2-1; 12 PDSCH symbols, 12 DMRS REs per PRB, no xOverhead |
+| HARQ processes | TS 38.321 5.3.2; TS 38.331 PDSCH-ServingCellConfig | 8 per user (the number when nrofHARQ-ProcessesForPDSCH is absent); a new transport block needs a free process |
+| Retransmission | TS 38.321 5.3.2.2 (combined with the earlier data) | after `harq_rtt_slots`, chase combining (the SINRs of the transmissions add), at most `harq_max_tx` transmissions (the number is the network's choice) |
+
+## 2. The block-error probability
+
+3GPP gives no curve of block errors against SINR; it is a property of the receiver. HandoverLab
+uses the normal approximation of the error probability of a code of finite length (Polyanskiy,
+Poor and Verdu, IEEE Trans. Inf. Theory 56(5), 2010) on the bit channel of the modulation: the
+mutual information C and the dispersion V per coded bit of QPSK, 16QAM and 64QAM with Gray mapping
+(computed by quadrature), and P_e = Q((n C - k + log2(n) / 2) / sqrt(n V)) for n coded bits and
+k = TBS + 24 information bits, at the SINR less `l2s_loss_db` (the gap of a practical LDPC decoder,
+an assumption). For 51 PRBs the 10 % points run from about -6 dB (MCS 0) to about 19 dB (MCS 28);
+at each of them the spectral efficiency of the MCS lies below the Shannon capacity. No block-error
+table of another simulator is used.
+
+## 3. Cost and limits
+
+- Every slot is played: about 45 times the time of the default rate model (10 users on the ns-3
+  card: about 90 s instead of 2 s for 20 s simulated). Use it for focused studies; a compiled loop
+  is planned.
+- The channel is held for the 10 ms step; mobility decisions stay on the 10 ms grid.
+- This version needs the base engine (no beams, layers, NTN or TS 38.133 periods).
+- Data of a user stop during a handover interruption and wait in its buffer; forwarding between
+  cells, RLC and PDCP are the next item of the roadmap.
+- The decoding draws come from the world's stream `harq`, one number per user and slot whatever the
+  decisions, so every rule compared on one seed sees the same draws.
+
+## 4. Checks
+
+`tests/test_scheduler.py` holds the criteria fixed before the code: the MCS and CQI tables against
+the text, six transport block sizes worked out by hand from clause 5.1.3.2 (both branches of
+R <= 1/4 and N'_info > 8424), the properties of the block-error model, equal round-robin shares,
+equal long-run proportional-fair time shares, the loss of p^4 of the blocks after four failed
+transmissions, and that the option off changes no fingerprint.

{handoverlab-2.1.0 → handoverlab-2.2.0}/docs/reference/cli.md

@@ -60,8 +60,8 @@ options:
   -h, --help            show this help message and exit
   --only GROUP [GROUP ...]
                         check groups: pathloss radio calibration invariants equivalences
-                        fingerprints extended highway (default: all of them); on request only:
-                        learning ntn
+                        fingerprints extended highway values fading (default: all of them); on
+                        request only: learning ntn
   --full                longer checks (three seeds for the radio statistics)
   --ns3                 compare with the stored ns-3 / 5G-LENA results (several minutes); only
                         this check unless --only names groups

{handoverlab-2.1.0 → handoverlab-2.2.0}/docs/scenarios/highway-tr37885-30ghz.md

@@ -51,6 +51,9 @@ Values in **bold** differ from the HandoverLab defaults.
 | `radio.energy_p0_w` | 56 | EARTH model, micro base station (Auer et al. 2011, Table 2): 56 W |
 | `radio.energy_slope` | 2.6 | EARTH model, micro base station (Auer et al. 2011, Table 2): 2.6 |
 | `radio.energy_ntrx` | 2 | EARTH model, micro base station (Auer et al. 2011, Eq. 1 and Table 2): 2 transceivers |
+| `radio.fast_fading` | none | off by default; TR 38.901 clause 7.7.2 (TDL-A .. TDL-E) |
+| `radio.delay_spread_ns` | 100 | TR 38.901 Table 7.7.3-1 (nominal delay spread; used with fast_fading) |
+| `radio.fading_k_db` | none | TR 38.901 clause 7.7.6 (unset: the K-factor of the table) |
 | `radio.map_res_m` | **2** | numerical setting |
 | `radio.beams.sectors` | 3 | TR 36.885 clause A.1.3, option 2 (19 x 3 hexagonal cells) |
 | `radio.beams.sector_az0_deg` | **6.587** | TR 38.901 Table 7.8-1 (3 sectors per cell site: 30, 150 and 270 degrees), turned by -23.413 degrees with the layout |
@@ -94,6 +97,10 @@ Values in **bold** differ from the HandoverLab defaults.
 | `protocol.lm_load_per_ue` | 0 | off by default (calibration option) |
 | `protocol.exec_can_fail` | true | TR 36.839: the execution fails when the target is below Qout |
 | `protocol.rlm_holdoff_s` | 0.2 | 0.2 s since 2.0.0: an interpretation of TS 38.133 8.1.2.2 (evaluation over the last T_Evaluate_out, 200 ms in FR1) on a newly joined cell |
+| `protocol.scheduler` | none | off by default (rate model); rr / pf slot scheduler with TS 38.214 MCS and TBS |
+| `protocol.harq_max_tx` | 4 | assumption (transmissions per TB; the network's choice) |
+| `protocol.harq_rtt_slots` | 8 | assumption (HARQ round trip in slots) |
+| `protocol.l2s_loss_db` | 1 | assumption (implementation loss of the block-error model) |
 | `protocol.rrc_detail` | 3gpp |  |
 | `traffic.services` | 5 entries | TS 23.501 Table 5.7.4-1 (5QI); thresholds are assumptions |
 | `traffic.se_max` | 7.4 | assumption (spectral-efficiency cap) |

{handoverlab-2.1.0 → handoverlab-2.2.0}/docs/scenarios/highway-tr37885-4ghz.md

@@ -55,6 +55,9 @@ Values in **bold** differ from the HandoverLab defaults.
 | `radio.energy_p0_w` | 56 | EARTH model, micro base station (Auer et al. 2011, Table 2): 56 W |
 | `radio.energy_slope` | 2.6 | EARTH model, micro base station (Auer et al. 2011, Table 2): 2.6 |
 | `radio.energy_ntrx` | 2 | EARTH model, micro base station (Auer et al. 2011, Eq. 1 and Table 2): 2 transceivers |
+| `radio.fast_fading` | none | off by default; TR 38.901 clause 7.7.2 (TDL-A .. TDL-E) |
+| `radio.delay_spread_ns` | 100 | TR 38.901 Table 7.7.3-1 (nominal delay spread; used with fast_fading) |
+| `radio.fading_k_db` | none | TR 38.901 clause 7.7.6 (unset: the K-factor of the table) |
 | `radio.map_res_m` | **4** | numerical setting (coarser map for the long road) |
 | `protocol.step_s` | 0.01 | numerical setting |
 | `protocol.l1_period_s` | 0.04 | assumption (L1 sample period) |
@@ -78,6 +81,10 @@ Values in **bold** differ from the HandoverLab defaults.
 | `protocol.lm_load_per_ue` | 0 | off by default (calibration option) |
 | `protocol.exec_can_fail` | true | TR 36.839: the execution fails when the target is below Qout |
 | `protocol.rlm_holdoff_s` | 0.2 | 0.2 s since 2.0.0: an interpretation of TS 38.133 8.1.2.2 (evaluation over the last T_Evaluate_out, 200 ms in FR1) on a newly joined cell |
+| `protocol.scheduler` | none | off by default (rate model); rr / pf slot scheduler with TS 38.214 MCS and TBS |
+| `protocol.harq_max_tx` | 4 | assumption (transmissions per TB; the network's choice) |
+| `protocol.harq_rtt_slots` | 8 | assumption (HARQ round trip in slots) |
+| `protocol.l2s_loss_db` | 1 | assumption (implementation loss of the block-error model) |
 | `protocol.rrc_detail` | 3gpp |  |
 | `traffic.services` | 5 entries | TS 23.501 Table 5.7.4-1 (5QI); thresholds are assumptions |
 | `traffic.se_max` | 7.4 | assumption (spectral-efficiency cap) |

{handoverlab-2.1.0 → handoverlab-2.2.0}/docs/standard-compliance.md

@@ -91,6 +91,7 @@ checks) and is part of `handoverlab.stability.LEGACY_1X`.
 | Soft LOS state, Eqs. (7.6-18), (7.6-19) | 7.6.3.3 | `radio.soft_los`: power weights LOS_soft^2 and 1 - LOS_soft^2 (no fast fading, so no cross term) | follows (power level) |
 | Multi-frequency: the same LOS state (Step 2) and LSPs (Step 4) on all frequencies of one link | 7.6.5 | layers with `cosited: true` reuse the random fields of the first layer; their `pathloss`, `los_corr_m` and `shadow_decorr_m` must equal those of the first layer (checked since 2.1.0); soft LOS may differ with the frequency, as 7.6.5 allows | follows |
 | O2I car penetration loss N(9, 5^2) per UT | 7.4.3.2 | `radio.penetration_db`, `penetration_sd_db` | follows (option) |
+| Fast fading: TDL-A .. TDL-E taps, Jakes Doppler per tap with f_D = \|v\| / lambda_0, LOS tap of TDL-D / -E at f_S = 0.7 f_D with K1 13.3 / 22 dB, delay scaling Eq. 7.7-1, K-factor change Eq. 7.7.6-1/-2 | 7.7.2 (Tables 7.7.2-1 to -5), 7.7.3, 7.7.6 | `radio.fast_fading` (2.2.0, off by default), `delay_spread_ns`, `fading_k_db`: one TDL per scenario, independent per user-cell link, 32 sinusoids per Rayleigh tap, channel at 4 points of the PDCCH band and 8 of the carrier ([guide](guides/fading.md)); MIMO extension 7.7.5 and CDL not used | follows (option; single-link TDL) |
 
 ## Map-based channel model (1.12.0, `radio.map_file`)
 
@@ -152,6 +153,7 @@ measurements can be read in the same format, but they are outside TR 38.901 (**a
 | T312 (optional, useT312) | TS 38.331 5.3.10, 5.5.4.1 | not modelled | not modelled (optional feature) |
 | Link monitoring restarts on a newly joined cell: the quality is evaluated over the last T_Evaluate_out | TS 38.133 8.1.2.2 (interpretation; no clause defines a hold-off) | `protocol.rlm_holdoff_s` (0.2 s, default since 2.0.0): no out-of-sync for this time after joining a cell, whatever the frequency range | abstraction (interpretation of 8.1.2.2) |
 | In-car penetration loss per user, 9 dB +- 5 dB | TR 38.901 7.4.3.2 | `radio.penetration_db`, `penetration_sd_db`, any speed | follows (option) |
+| Qout / Qin as the BLER of a hypothetical PDCCH on the faded channel | TS 38.133 8.1, Tables 8.1.2.1-1/-2 (QPSK, 24 PRBs) | with `radio.fast_fading` (2.2.0): the MIESM effective SINR of QPSK over the 24-PRB band against `qout_db` / `qin_db` (flat-channel SINRs); without it the wideband SINR | abstraction (no link-level BLER curve) |
 
 ## Handover procedure
 
@@ -203,6 +205,17 @@ and the FR2 limit of 64 SSBs. The evaluation periods of TS 38.133 are minimum re
 longest time a UE may take); HandoverLab uses them as the averaging time constants, a conservative
 reading.
 
+## Data plane (2.2.0, `protocol.scheduler`)
+
+| What the texts specify | Clause | HandoverLab | Status |
+|---|---|---|---|
+| Slots: 2^mu slots per 1 ms subframe | TS 38.211 Table 4.3.2-1 | slot length 1 ms / 2^mu of the carrier's subcarrier spacing | follows |
+| MCS index table 1 for PDSCH (Q_m, target code rate) | TS 38.214 Table 5.1.3.1-1 | the 29 rows; the highest MCS with a block-error probability of at most 10 % at the reported SINR | follows (table); link adaptation: implementation |
+| Transport block size | TS 38.214 5.1.3.2, Table 5.1.3.2-1 | steps 1 to 4; 12 PDSCH symbols, 12 DMRS REs per PRB, xOverhead 0, one layer | follows |
+| HARQ entity per serving cell, parallel processes, retransmission decoded with the earlier data | TS 38.321 5.3.2.1, 5.3.2.2 | 8 processes per user (TS 38.331: absent nrofHARQ-ProcessesForPDSCH), chase combining, at most `harq_max_tx` transmissions after `harq_rtt_slots` | follows (combining and the number of transmissions: implementation choices) |
+| Block errors of a transport block | not specified (receiver property) | normal approximation of the finite-blocklength error probability on the BICM bit channel, with an implementation loss | abstraction |
+| Scheduling | not specified (gNB) | round robin in frequency or proportional fair in time | abstraction |
+
 ## Beyond 5G: what is not modelled yet
 
 | Rule | Clause | Status |
@@ -235,7 +248,7 @@ The ns-3 / 5G-LENA build of the comparison study was read at the source (contrib
 | CHO, DAPS, LTM, conditional LTM (Rel-16 to 19) | none | all four |
 | Beam failure recovery | none | none |
 | Large-scale channel calibration (TR 38.901 7.8.1) | calibrated by its authors | calibrated (see [radio calibration](calibration-3gpp.md)) |
-| Fast fading, packet-level PHY/MAC/RLC | yes | no (received-power level) |
+| Fast fading, packet-level PHY/MAC/RLC | yes | options since 2.2.0: TDL fast fading, a slot scheduler with MCS, TBS and HARQ; no RLC / PDCP |
 
 **Reading.** On the rules of the handover procedure and on the procedures of Releases 16 to 19,
 HandoverLab with the 3GPP profile follows the normative texts more closely; on the physical layer

{handoverlab-2.1.0 → handoverlab-2.2.0}/docs/user_guide.md

@@ -226,6 +226,7 @@ output: results/metrics.csv
 | | `time_var_db`, `time_var_tau_s` | `1.5`, `1` | time-varying component (moving blockers) |
 | | `l1_error_db` | `1` | error of one L1 RSRP sample |
 | | `energy_p0_w`, `energy_slope`, `energy_ntrx` | `56`, `2.6`, `2` | cell power for the energy metrics (1.5.0; `energy_ntrx` since 2.1.0): EARTH model of a micro base station, Auer et al. 2011 Eq. 1 and Table 2 |
+| | `fast_fading`, `delay_spread_ns`, `fading_k_db` | `null`, `100`, `null` | (2.2.0) TDL fast fading of TR 38.901 clause 7.7.2 (`tdl-a` .. `tdl-e`), its RMS delay spread and an optional K-factor; radio-link monitoring and the rate then use effective SINRs ([guide](guides/fading.md)) |
 | | `penetration_db`, `penetration_sd_db` | `0`, `0` | optional (1.2.0): penetration loss of each user on all its links, drawn once per user (TR 38.901 clause 7.4.3.2: `9`, `5` for a user in a standard car) |
 | | `map_res_m` | `1` | radio-map resolution (street grid) |
 | | `scs_khz` | none | optional (1.10.0): subcarrier spacing for SS-RSRP per resource element; unset: 30 kHz up to 7.125 GHz, 120 kHz above |
@@ -245,6 +246,8 @@ output: results/metrics.csv
 | | `cfg_loss_as_failure` | `false` | check mode: a lost conditional configuration fails like a lost handover command |
 | | `lm_load`, `lm_load_per_ue` | `null`, `0` | optional (1.1.0): interferer load at link monitoring, plus a part per user served by the interfering cell; `null` and `0` keep the load of the data channel ([calibration](calibration.md)) |
 | | `exec_can_fail` | `true` | `false`: the execution always joins the target (ideal random access) |
+| | `rrc_detail` | `3gpp` | since 2.1.0: `3gpp` -- the procedures as audited against TS 38.331 / TS 38.133 / TS 38.300 (RLM counters and indication interval, DAPS source monitoring, LTM candidates kept, CHO at TTT expiry, outcome classes, RRC messages one by one, ...); `simple` -- the engine of 2.0.0 (part of `LEGACY_1X`) |
+| | `scheduler`, `harq_max_tx`, `harq_rtt_slots`, `l2s_loss_db` | `null`, `4`, `8`, `1.0` | (2.2.0) slot scheduler `rr` or `pf` with MCS table 1 and the TBS of TS 38.214, HARQ with 8 processes and chase combining; null keeps the rate model ([guide](guides/scheduler.md)) |
 | | `rlm_holdoff_s` | `0.2` | no out-of-sync on a newly joined cell for this time, as radio-link monitoring restarts there (an interpretation of TS 38.133 8.1.2.2; since 1.3.0, default since 2.0.0; 1.x: `0`) |
 | | `cmd_during_t310` | `receive` | (1.9.0; default since 2.0.0, 1.x: `lost`) a handover or cell switch command that reaches the UE while T310 runs is received at the first step with link-monitoring SINR >= Qout and stops T310 (TS 38.331 5.3.5.5.2); since 2.0.0 a CHO or LTM candidate configuration is received the same way, without stopping T310 (5.3.5.13) |
 | | `t304_s` | `1.0` | T304 (1.9.0; default since 2.0.0, 1.x: none): the execution fails only when T304 expires; the UE joins at the first step with target SINR >= Qout (TS 38.331 5.3.5.8.3) |
@@ -817,8 +820,10 @@ intervals are wide; the report shows them next to every estimate.
 
 ## 12. Limitations
 
-- Received-power level only: no link-level physical layer, no fast fading, no HARQ, no beam
-  management (one beam gain and one isolation factor), no packet-level protocol stack.
+- Received-power level by default: no link-level physical layer, no HARQ, no beam management (one
+  beam gain and one isolation factor), no packet-level protocol stack; fast fading with effective
+  SINRs and a slot scheduler with MCS and HARQ are options since 2.2.0 ([fading](guides/fading.md),
+  [scheduler](guides/scheduler.md)).
 - The failure model uses the SINR thresholds and timers of TR 36.839 with the procedures of TS 38.331 and
   TS 38.133 (see [standard compliance](standard-compliance.md)); it is not calibrated in absolute terms, so
   failure rates are best read relative to each other.

{handoverlab-2.1.0 → handoverlab-2.2.0}/docs/verification.md

@@ -33,6 +33,7 @@ writes the report with the versions of Python, NumPy and SciPy and the platform.
 | TR 37.885 highway (1.11.0) | geometry and link budget of the two highway cards against TR 37.885, TR 36.885 and TR 38.901; continuity of the received power at the wrap-around; coupling gain to the strongest site against an independent computation (percentiles 5-95 within 0.5 dB); LOS on every link | `verify` group `highway`, `tests/test_highway_tr37885.py` |
 | Legacy settings (2.0.0) | every golden run of 1.12.0 repeated with `LEGACY_1X`: identical event logs (33 of 33) | `verify` group `fingerprints` (section `fingerprints-1x`) |
 | Satellite (2.0.0) | N1 link budget of the 8 S-band LEO cases of TR 38.821 Table 6.1.3.3-1 within 0.1 dB (passed, 0.028 dB); N2 3 dB beamwidth within 0.01 degree of Tables 6.1.1.1-1/-2 (failed for 1 m: 0.014 degree; see the [NTN guide](guides/ntn.md)); N3 orbital speed and nadir footprint (passed) | `verify --only ntn` |
+| Fast fading (2.2.0) | the TDL taps of TR 38.901 clause 7.7.2: Rayleigh with unit power (KS test), the J0 time correlation of the Jakes spectrum, the K-factor of the first TDL-D tap, the delay spread after Eq. 7.7-1 and after a K change (Eq. 7.7.6-1/-2); the effective-SINR mappings exact on a flat channel and never above the mean; the option off changes no fingerprint | `verify` group `fading`, `tests/test_fading.py` |
 | Learning rule (1.11.0) | `a3_bandit` against an exhaustive search over its arms, three criteria fixed before the run (one failed: see the [learning-rule guide](guides/learning-rule.md)) | `verify --only learning` (about 20 minutes) |
 | Imported radio maps (1.12.0) | an exported street-grid map imported again gives the identical event log (every golden case on the street grid); interpolation of measured points with its hold-out error; errors for a wrong format, other sites, a map that does not cover the area, a changed file | `tests/test_mapfile.py` |
 | Compiled kernel (1.11.0) | the golden fingerprints with `run.backend: numba` | `tests/test_v111.py` (with Numba installed) |

{handoverlab-2.1.0 → handoverlab-2.2.0}/mkdocs.yml

@@ -36,6 +36,8 @@ nav:
       - Indoor and rural scenarios: guides/indoor-rural.md
       - Mobility robustness optimisation: guides/mro.md
       - Beams and several carriers: guides/beams-layers.md
+      - Fast fading and effective SINR: guides/fading.md
+      - Slot scheduler, MCS and HARQ: guides/scheduler.md
       - Your own radio map: guides/radio-maps.md
       - A LEO satellite (NTN): guides/ntn.md
       - Moving from 1.x to 2.0: migration-2.0.md

{handoverlab-2.1.0 → handoverlab-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "handoverlab"
-version = "2.1.0"
+version = "2.2.0"
 description = "System-level handover simulator for 5G-Advanced and beyond-5G research"
 readme = "README.md"
 license = "MIT"

{handoverlab-2.1.0 → handoverlab-2.2.0}/src/handoverlab/__init__.py

@@ -10,7 +10,7 @@ Quick start::
     for r in res:
         print(r.rule, r.metrics["handovers_pm"], r.metrics["failures_pm"])
 """
-__version__ = "2.1.0"
+__version__ = "2.2.0"
 
 from .config import (ConfigError, Experiment, LayoutConfig, MobilityConfig, ProtocolConfig, RadioConfig, RunConfig,
                      Scenario, Service, SpeedGroup, TrafficConfig, load_config)

handoverlab-2.2.0/src/handoverlab/channel/fading.py

@@ -0,0 +1,157 @@
+# SPDX-License-Identifier: MIT
+"""Fast fading with the tapped delay line (TDL) models of TR 38.901 (optional, since 2.2.0).
+
+``radio.fast_fading`` selects one of TDL-A .. TDL-E (TR 38.901 V19.5.0 clause 7.7.2, Tables 7.7.2-1 to
+7.7.2-5).  Each user-cell link fades independently:
+
+* the normalised delays are scaled to the RMS delay spread ``radio.delay_spread_ns`` (Eq. 7.7-1,
+  tau_scaled = tau_model x DS; Table 7.7.3-1 gives 10, 30, 100, 300 and 1000 ns as examples);
+* for TDL-D and TDL-E the K-factor can be changed (``radio.fading_k_db``; Eq. 7.7.6-1 and 7.7.6-2, after
+  which the delays are re-normalised to DS = 1);
+* every Rayleigh tap is a sum of sinusoids with random arrival angles and phases, so that its Doppler
+  spectrum tends to the classical (Jakes) shape with the maximum Doppler shift f_D = |v| / lambda_0 (|v| the
+  user's speed, lambda_0 the carrier wavelength); the phases advance by one step at a time;
+* the LOS tap of TDL-D / TDL-E is a specular component with the Doppler shift f_S = 0.7 f_D;
+* the tap powers are normalised to a unit sum, so the mean power gain of a link is 1 and the large-scale model
+  is unchanged on average.
+
+The channel is evaluated at a few frequencies: points spread over the 24-PRB band of the hypothetical PDCCH of
+radio-link monitoring (TS 38.133 Tables 8.1.2.1-1/-2) and points spread over the carrier bandwidth (the
+transmission bandwidth configuration of TS 38.101-1/-2 Table 5.3.2-1).
+"""
+from __future__ import annotations
+
+import math
+from typing import Dict, Optional, Tuple
+
+import numpy as np
+
+C0 = 3.0e8                      # TR 38.901 Table 7.4.1-1 note: c = 3.0 x 10^8 m/s
+
+#: TR 38.901 V19.5.0 Tables 7.7.2-1 to 7.7.2-5: (normalised delay, power [dB], kind) per tap; kind "L" is the LOS
+#: path of TDL-D / TDL-E (the Rayleigh part of their first tap follows it at the same delay)
+TDL: Dict[str, Tuple[Tuple[float, float, str], ...]] = {
+    "tdl-a": ((0.0000, -13.4, "R"), (0.3819, 0.0, "R"), (0.4025, -2.2, "R"), (0.5868, -4.0, "R"),
+              (0.4610, -6.0, "R"), (0.5375, -8.2, "R"), (0.6708, -9.9, "R"), (0.5750, -10.5, "R"),
+              (0.7618, -7.5, "R"), (1.5375, -15.9, "R"), (1.8978, -6.6, "R"), (2.2242, -16.7, "R"),
+              (2.1718, -12.4, "R"), (2.4942, -15.2, "R"), (2.5119, -10.8, "R"), (3.0582, -11.3, "R"),
+              (4.0810, -12.7, "R"), (4.4579, -16.2, "R"), (4.5695, -18.3, "R"), (4.7966, -18.9, "R"),
+              (5.0066, -16.6, "R"), (5.3043, -19.9, "R"), (9.6586, -29.7, "R")),
+    "tdl-b": ((0.0000, 0.0, "R"), (0.1072, -2.2, "R"), (0.2155, -4.0, "R"), (0.2095, -3.2, "R"),
+              (0.2870, -9.8, "R"), (0.2986, -1.2, "R"), (0.3752, -3.4, "R"), (0.5055, -5.2, "R"),
+              (0.3681, -7.6, "R"), (0.3697, -3.0, "R"), (0.5700, -8.9, "R"), (0.5283, -9.0, "R"),
+              (1.1021, -4.8, "R"), (1.2756, -5.7, "R"), (1.5474, -7.5, "R"), (1.7842, -1.9, "R"),
+              (2.0169, -7.6, "R"), (2.8294, -12.2, "R"), (3.0219, -9.8, "R"), (3.6187, -11.4, "R"),
+              (4.1067, -14.9, "R"), (4.2790, -9.2, "R"), (4.7834, -11.3, "R")),
+    "tdl-c": ((0.0, -4.4, "R"), (0.2099, -1.2, "R"), (0.2219, -3.5, "R"), (0.2329, -5.2, "R"),
+              (0.2176, -2.5, "R"), (0.6366, 0.0, "R"), (0.6448, -2.2, "R"), (0.6560, -3.9, "R"),
+              (0.6584, -7.4, "R"), (0.7935, -7.1, "R"), (0.8213, -10.7, "R"), (0.9336, -11.1, "R"),
+              (1.2285, -5.1, "R"), (1.3083, -6.8, "R"), (2.1704, -8.7, "R"), (2.7105, -13.2, "R"),
+              (4.2589, -13.9, "R"), (4.6003, -13.9, "R"), (5.4902, -15.8, "R"), (5.6077, -17.1, "R"),
+              (6.3065, -16.0, "R"), (6.6374, -15.7, "R"), (7.0427, -21.6, "R"), (8.6523, -22.8, "R")),
+    "tdl-d": ((0.0, -0.2, "L"), (0.0, -13.5, "R"), (0.035, -18.8, "R"), (0.612, -21.0, "R"), (1.363, -22.8, "R"),
+              (1.405, -17.9, "R"), (1.804, -20.1, "R"), (2.596, -21.9, "R"), (1.775, -22.9, "R"),
+              (4.042, -27.8, "R"), (7.937, -23.6, "R"), (9.424, -24.8, "R"), (9.708, -30.0, "R"),
+              (12.525, -27.7, "R")),
+    "tdl-e": ((0.0, -0.03, "L"), (0.0, -22.03, "R"), (0.5133, -15.8, "R"), (0.5440, -18.1, "R"),
+              (0.5630, -19.8, "R"), (0.5440, -22.9, "R"), (0.7112, -22.4, "R"), (1.9092, -18.6, "R"),
+              (1.9293, -20.8, "R"), (1.9589, -22.6, "R"), (2.6426, -22.3, "R"), (3.7136, -25.6, "R"),
+              (5.4524, -20.2, "R"), (12.0034, -29.8, "R"), (20.6519, -29.2, "R")),
+}
+MODELS = tuple(TDL)
+#: K-factor of the first tap given in the notes of Tables 7.7.2-4 / 7.7.2-5 [dB]
+K_MODEL_DB = {"tdl-d": 13.3, "tdl-e": 22.0}
+N_SINUSOIDS = 32                # sinusoids per Rayleigh tap (16 left a measurable deviation from Rayleigh)
+PDCCH_PRB = 24                  # bandwidth of the hypothetical PDCCH (TS 38.133 Tables 8.1.2.1-1/-2)
+
+
+def rms_delay_spread(delays: np.ndarray, powers: np.ndarray) -> float:
+    """RMS delay spread of a power delay profile (linear powers)."""
+    p = powers / powers.sum()
+    m = float((p * delays).sum())
+    return math.sqrt(max(float((p * delays ** 2).sum()) - m * m, 0.0))
+
+
+def tdl_profile(model: str, ds_s: float, k_db: Optional[float] = None) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Delays [s], linear powers (unit sum) and LOS flags of the taps of ``model`` at RMS delay spread ``ds_s``.
+
+    With ``k_db`` (TDL-D / TDL-E only) the Rayleigh tap powers follow Eq. 7.7.6-1, P_scaled = P_model - K_desired
+    + K_model, with K_model of Eq. 7.7.6-2: the LOS power over the sum of the powers of the taps that are rescaled
+    (the Rayleigh taps); the delays are then divided by the RMS delay spread that results, so that DS = 1 before
+    the scaling of Eq. 7.7-1.
+    """
+    taps = TDL[model]
+    tau = np.array([t[0] for t in taps])
+    p_db = np.array([t[1] for t in taps])
+    los = np.array([t[2] == "L" for t in taps])
+    if k_db is not None:
+        if not los.any():
+            raise ValueError("a K-factor applies to the LOS models tdl-d and tdl-e only")
+        k_model = p_db[los][0] - 10.0 * np.log10(np.sum(10.0 ** (p_db[~los] / 10.0)))    # Eq. 7.7.6-2
+        p_db = np.where(los, p_db, p_db - k_db + k_model)                                  # Eq. 7.7.6-1
+        p_lin = 10.0 ** (p_db / 10.0)
+        tau = tau / rms_delay_spread(tau, p_lin)
+    p = 10.0 ** (p_db / 10.0)
+    return tau * ds_s, p / p.sum(), los
+
+
+def k_factor_db(model: str, k_db: Optional[float] = None) -> float:
+    """K-factor of Eq. 7.7.6-2: LOS power over the sum of the Rayleigh tap powers [dB]."""
+    _, p, los = tdl_profile(model, 1.0, k_db)
+    return float(10.0 * np.log10(p[los].sum() / p[~los].sum()))
+
+
+def first_tap_k_db(model: str) -> float:
+    """K-factor of the first tap alone, as the notes of Tables 7.7.2-4 / 7.7.2-5 give it [dB]."""
+    _, p, los = tdl_profile(model, 1.0)
+    first = np.nonzero(los)[0][0]
+    return float(10.0 * np.log10(p[first] / p[first + 1]))
+
+
+def frequencies(bandwidth_mhz: float, scs_khz: float, n_rb: Optional[int], n_rlm: int = 4,
+                n_data: int = 8) -> Tuple[np.ndarray, np.ndarray]:
+    """Offsets [Hz] from the carrier centre of the PDCCH points (24 PRBs around the centre) and the data points."""
+    rb_hz = 12.0 * scs_khz * 1e3
+    n = n_rb if n_rb is not None else int(bandwidth_mhz * 1e3 / (12.0 * scs_khz))
+    w_rlm = min(PDCCH_PRB, n) * rb_hz
+    w_data = n * rb_hz
+    centre = lambda w, k: (np.arange(k) + 0.5) / k * w - w / 2.0          # noqa: E731
+    return centre(w_rlm, n_rlm), centre(w_data, n_data)
+
+
+class TdlFading:
+    """Independent TDL fading of ``U`` x ``M`` links evaluated at the frequencies ``f_hz``.
+
+    ``fd`` (U,) are the users' maximum Doppler shifts [Hz]; each call of :meth:`gains` advances every link by one
+    step of ``dt`` seconds and returns |H|^2 (U, M, F).  The draws come from ``rng`` once, at construction; every
+    sinusoid then turns by a fixed phase per step (one complex multiplication), as the speed of a user is constant.
+    """
+
+    def __init__(self, rng: np.random.Generator, U: int, M: int, model: str, ds_s: float, f_hz: np.ndarray,
+                 dt: float, fd: np.ndarray, k_db: Optional[float] = None, n_sin: int = N_SINUSOIDS):
+        tau, p, los = tdl_profile(model, ds_s, k_db)
+        ray = ~los
+        L = int(ray.sum())
+        w = 2.0 * np.pi * dt * np.asarray(fd, dtype=float)                       # phase per step at f_D (U,)
+        # Rayleigh taps: sum of n_sin sinusoids with uniform arrival angles and phases (Clarke / Jakes spectrum)
+        cos_a = np.cos(rng.uniform(0.0, 2.0 * np.pi, (U, M, L, n_sin)))
+        self.z = np.exp(1j * rng.uniform(0.0, 2.0 * np.pi, (U, M, L, n_sin))).reshape(U, M, L * n_sin)
+        self.rot = np.exp(1j * w[:, None, None, None] * cos_a).reshape(U, M, L * n_sin)
+        f = np.asarray(f_hz, dtype=float)
+        e_ray = np.sqrt(p[ray])[:, None] * np.exp(-2j * np.pi * tau[ray][:, None] * f[None, :])        # (L, F)
+        self.e = np.repeat(e_ray, n_sin, axis=0) / math.sqrt(n_sin)                                    # (L n, F)
+        self.los = bool(los.any())
+        if self.los:                    # specular LOS component at f_S = 0.7 f_D with a random start phase
+            self.e_los = np.sqrt(p[los][0]) * np.exp(-2j * np.pi * tau[los][0] * f)                    # (F,)
+            self.z_los = np.exp(1j * rng.uniform(0.0, 2.0 * np.pi, (U, M)))
+            self.rot_los = np.exp(1j * 0.7 * w)[:, None]
+        self.n_f = len(f)
+
+    def gains(self) -> np.ndarray:
+        """|H|^2 of every link at every frequency after one more step (U, M, F)."""
+        self.z *= self.rot
+        h = self.z @ self.e                                                        # (U, M, F)
+        if self.los:
+            self.z_los *= self.rot_los
+            h += self.z_los[..., None] * self.e_los
+        return h.real ** 2 + h.imag ** 2