handoverlab 1.0.0__py3-none-any.whl

handoverlab/__init__.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: MIT
+"""HandoverLab: system-level simulation of handover and mobility procedures.
+
+Quick start::
+
+    import handoverlab as hl
+
+    sc = hl.Scenario()                                  # 3 x 3-block street grid, 10 GHz
+    res = hl.simulate(sc, [{"rule": "a3"}, {"rule": "cho"}], seeds=[1])
+    for r in res:
+        print(r.rule, r.metrics["handovers_pm"], r.metrics["failures_pm"])
+"""
+__version__ = "1.0.0"
+
+from .config import (ConfigError, Experiment, LayoutConfig, MobilityConfig, ProtocolConfig, RadioConfig, RunConfig,
+                     Scenario, Service, SpeedGroup, TrafficConfig, load_config)
+from .engine import InvariantError
+from .eventlog import fingerprint, read_events, write_events
+from .rules import (A3, CHO, DAPS, LTM, BaselineRule, ConditionalRule, DAPSRule, LTMRule, Rule, available_rules,
+                    make_rule, register_rule)
+from .scenarios import builtin_scenario, scenario_card, scenario_names
+from .simulate import RunResult, run_experiment, run_world, simulate
+from .world import World, build_world
+
+__all__ = ["__version__", "ConfigError", "Experiment", "LayoutConfig", "MobilityConfig", "ProtocolConfig",
+           "RadioConfig", "RunConfig", "Scenario", "Service", "SpeedGroup", "TrafficConfig", "load_config",
+           "A3", "CHO", "DAPS", "LTM", "BaselineRule", "ConditionalRule", "DAPSRule", "LTMRule", "Rule",
+           "available_rules", "make_rule", "register_rule",
+           "RunResult", "run_experiment", "run_world", "simulate", "World", "build_world", "InvariantError",
+           "fingerprint", "read_events", "write_events", "builtin_scenario", "scenario_card", "scenario_names"]

handoverlab/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: MIT
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

handoverlab/channel/__init__.py

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: MIT
+"""Radio channel: TR 38.901 path loss, place-tied radio map, per-run radio samples."""
+from .pathloss import breakpoint_distance, p_los, p_los_uma, p_los_umi, path_loss, uma_los, uma_nlos, umi_los, umi_nlos
+from .radiomap import RadioMap
+from .source import Chunk, RadioSource
+
+__all__ = ["breakpoint_distance", "p_los", "p_los_uma", "p_los_umi", "path_loss", "uma_los", "uma_nlos",
+           "umi_los", "umi_nlos", "RadioMap", "Chunk", "RadioSource"]

handoverlab/channel/pathloss.py

@@ -0,0 +1,122 @@
+# SPDX-License-Identifier: MIT
+"""Path loss and LOS probability of 3GPP TR 38.901 (Tables 7.4.1-1 and 7.4.2-1).
+
+Implemented: UMi street canyon and UMa, LOS and NLOS, outdoor users.
+Distances in metres, carrier frequency in GHz, results in dB.  The formulas
+are specified for 0.5-100 GHz.
+"""
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+C0 = 299792458.0
+
+
+def breakpoint_distance(fc_ghz: float, h_bs: float, h_ut: float, h_e: float = 1.0) -> float:
+    """d'_BP = 4 h'_BS h'_UT f_c / c with effective heights h' = h - h_E [m]."""
+    return 4.0 * (h_bs - h_e) * (h_ut - h_e) * fc_ghz * 1e9 / C0
+
+
+def umi_los(d2d, fc_ghz: float, h_bs: float = 10.0, h_ut: float = 1.5):
+    """UMi street canyon, LOS (PL1 below the breakpoint distance, PL2 above)."""
+    dh2 = (h_bs - h_ut) ** 2
+    d3 = np.sqrt(d2d * d2d + dh2)
+    dbp = breakpoint_distance(fc_ghz, h_bs, h_ut)
+    lf = 20.0 * math.log10(fc_ghz)
+    pl1 = 32.4 + 21.0 * np.log10(d3) + lf
+    pl2 = 32.4 + 40.0 * np.log10(d3) + lf - 9.5 * math.log10(dbp * dbp + dh2)
+    return np.where(d2d <= dbp, pl1, pl2)
+
+
+def _umi_nlos_prime(d2d, fc_ghz, h_bs, h_ut):
+    d3 = np.sqrt(d2d * d2d + (h_bs - h_ut) ** 2)
+    return 35.3 * np.log10(d3) + 22.4 + 21.3 * math.log10(fc_ghz) - 0.3 * (h_ut - 1.5)
+
+
+def umi_nlos(d2d, fc_ghz: float, h_bs: float = 10.0, h_ut: float = 1.5):
+    """UMi street canyon, NLOS: max(PL_LOS, PL'_NLOS)."""
+    return np.maximum(umi_los(d2d, fc_ghz, h_bs, h_ut), _umi_nlos_prime(d2d, fc_ghz, h_bs, h_ut))
+
+
+def uma_los(d2d, fc_ghz: float, h_bs: float = 25.0, h_ut: float = 1.5):
+    """UMa, LOS (effective environment height 1 m)."""
+    dh2 = (h_bs - h_ut) ** 2
+    d3 = np.sqrt(d2d * d2d + dh2)
+    dbp = breakpoint_distance(fc_ghz, h_bs, h_ut)
+    lf = 20.0 * math.log10(fc_ghz)
+    pl1 = 28.0 + 22.0 * np.log10(d3) + lf
+    pl2 = 28.0 + 40.0 * np.log10(d3) + lf - 9.0 * math.log10(dbp * dbp + dh2)
+    return np.where(d2d <= dbp, pl1, pl2)
+
+
+def _uma_nlos_prime(d2d, fc_ghz, h_bs, h_ut):
+    d3 = np.sqrt(d2d * d2d + (h_bs - h_ut) ** 2)
+    return 13.54 + 39.08 * np.log10(d3) + 20.0 * math.log10(fc_ghz) - 0.6 * (h_ut - 1.5)
+
+
+def uma_nlos(d2d, fc_ghz: float, h_bs: float = 25.0, h_ut: float = 1.5):
+    """UMa, NLOS: max(PL_LOS, PL'_NLOS)."""
+    return np.maximum(uma_los(d2d, fc_ghz, h_bs, h_ut), _uma_nlos_prime(d2d, fc_ghz, h_bs, h_ut))
+
+
+_MODELS = {"umi_street_canyon": (umi_los, _umi_nlos_prime), "uma": (uma_los, _uma_nlos_prime)}
+
+# coefficients of the formulas above: LOS (A + B log10 d3 + 20 log10 fc; A + 40 log10 d3 + 20 log10 fc - C
+# log10(d'BP^2 + dh^2)) and NLOS' (D log10 d3 + E + F log10 fc - G (h_UT - 1.5))
+_COEF = {"umi_street_canyon": (32.4, 21.0, 9.5, 35.3, 22.4, 21.3, 0.3),
+         "uma": (28.0, 22.0, 9.0, 39.08, 13.54, 20.0, 0.6)}
+
+
+def path_loss(d2d, los, model: str, fc_ghz: float, h_bs: float, h_ut: float):
+    """Path loss of ``model`` ("umi_street_canyon" or "uma") for a boolean LOS state.
+
+    Gives exactly the values of ``np.where(los, X_los(...), X_nlos(...))``,
+    but computes the logarithm of the distance once, the second breakpoint
+    branch only where it applies and the rest in place (the radio map of a
+    large grid evaluates tens of millions of links).
+    """
+    if model not in _COEF:
+        raise ValueError("unknown path-loss model %r; known: %s" % (model, ", ".join(_MODELS)))
+    a, b, c, d, e, f, g = _COEF[model]
+    d2d = np.asarray(d2d, dtype=float)
+    scalar = d2d.ndim == 0
+    if scalar:
+        d2d = d2d.reshape(1)
+    dh2 = (h_bs - h_ut) ** 2
+    lg = np.log10(np.sqrt(d2d * d2d + dh2))
+    lf = 20.0 * math.log10(fc_ghz)
+    dbp = breakpoint_distance(fc_ghz, h_bs, h_ut)
+    pl = b * lg
+    pl += a                                             # same rounding as a + b * lg
+    pl += lf
+    far = d2d > dbp
+    if far.any():
+        pl[far] = a + 40.0 * lg[far] + lf - c * math.log10(dbp * dbp + dh2)
+    los = np.broadcast_to(np.asarray(los, dtype=bool), pl.shape)
+    if not los.all():
+        nl = d * lg                                     # NLOS' over the whole array, in place
+        nl += e
+        nl += f * math.log10(fc_ghz)
+        nl -= g * (h_ut - 1.5)
+        np.maximum(pl, nl, out=nl)
+        np.copyto(pl, nl, where=~los)
+    return pl.reshape(()) if scalar else pl
+
+
+def p_los_umi(d2d):
+    """LOS probability, UMi street canyon."""
+    d = np.maximum(np.asarray(d2d, dtype=float), 1e-9)
+    return np.where(d <= 18.0, 1.0, 18.0 / d + np.exp(-d / 36.0) * (1.0 - 18.0 / d))
+
+
+def p_los_uma(d2d):
+    """LOS probability, UMa, for h_UT <= 13 m."""
+    d = np.maximum(np.asarray(d2d, dtype=float), 1e-9)
+    return np.where(d <= 18.0, 1.0, 18.0 / d + np.exp(-d / 63.0) * (1.0 - 18.0 / d))
+
+
+def p_los(d2d, model: str):
+    """LOS probability for the named path-loss model."""
+    return p_los_umi(d2d) if model == "umi_street_canyon" else p_los_uma(d2d)

handoverlab/channel/radiomap.py

@@ -0,0 +1,198 @@
+# SPDX-License-Identifier: MIT
+"""Static radio map of one world: everything that is tied to place.
+
+For every map pixel in a street and every site the map stores
+
+* the line-of-sight state: blocked if the straight segment crosses a building
+  block, and (``clutter_los``) additionally the spatially consistent LOS state
+  of TR 38.901 clause 7.6.3.3 -- a Gaussian random field with ``los_corr_m``
+  correlation compared with the LOS probability -- standing for obstacles in
+  the street (vehicles, trees, street furniture).  The state is a property of
+  the place, the same for every user who passes there ("place-tied blockage");
+* the path loss for that state, and a static, spatially correlated shadowing
+  field shared by all users (share ``place_share`` of the shadowing variance).
+
+It also holds the operator's nominal best-server map (nearest site, no
+buildings, no shadowing), which is the only map a handover rule may use.
+
+In the open area there are no buildings; the map holds only the place-tied
+shadowing field, and the LOS state is drawn along each user's path by
+:class:`handoverlab.channel.source.RadioSource`.
+"""
+from __future__ import annotations
+
+import numpy as np
+from scipy.ndimage import gaussian_filter
+from scipy.spatial import cKDTree
+from scipy.special import ndtri
+
+from ..layout import Layout, los_matrix
+from ..seeds import streams
+from .pathloss import p_los, path_loss
+
+FLOOR_DB = -300.0
+
+
+class GaussianField:
+    """Unit-variance Gaussian random fields, one per site, on a raster.
+
+    Correlation exp(-(d / d_corr)^2); the fields of different sites share a
+    common component so that their mutual correlation is ``site_corr``.
+    """
+
+    def __init__(self, rng, layout: Layout, n_sites: int, d_corr: float, res: float, site_corr: float):
+        self.res = res
+        self.x0, self.y0 = layout.xmin - 2 * res, layout.ymin - 2 * res
+        self.nx = int((layout.xmax - layout.xmin) / res) + 6
+        self.ny = int((layout.ymax - layout.ymin) / res) + 6
+        s_pix = (d_corr / 2.0) / res
+        ca, cb = np.sqrt(site_corr), np.sqrt(1.0 - site_corr)
+
+        def one():
+            g = gaussian_filter(rng.standard_normal((self.ny, self.nx), dtype=np.float32), s_pix, mode="wrap")
+            return g / g.std()
+
+        common = one() if site_corr > 0 else 0.0
+        f = np.empty((n_sites, self.ny, self.nx), dtype=np.float32)     # one contiguous plane per site
+        for m in range(n_sites):
+            f[m] = ca * common + cb * one()
+        self.f = np.ascontiguousarray(f.transpose(1, 2, 0))              # (ny, nx, M) for fast lookups
+        self._flat = self.f.reshape(-1, n_sites)
+
+    def _weights(self, x, y):
+        gx = np.clip((x - self.x0) / self.res, 0.0, self.nx - 1.001)
+        gy = np.clip((y - self.y0) / self.res, 0.0, self.ny - 1.001)
+        ix, iy = gx.astype(int), gy.astype(int)
+        return iy * self.nx + ix, (gx - ix).astype(np.float32), (gy - iy).astype(np.float32)
+
+    def at(self, x, y) -> np.ndarray:
+        """Bilinear interpolation at points (P,) -> (P, M).
+
+        Evaluated as ``f00 (1-tx)(1-ty) + f10 tx (1-ty) + f01 (1-tx) ty + f11 tx ty``
+        from left to right, with the products in that order.
+        """
+        k, tx, ty = self._weights(x, y)
+        tx, ty = tx[:, None], ty[:, None]
+        ux, uy = 1 - tx, 1 - ty
+        f, nx = self._flat, self.nx
+        v = np.take(f, k, axis=0)
+        v *= ux
+        v *= uy
+        for kk, a, b in ((k + 1, tx, uy), (k + nx, ux, ty), (k + nx + 1, tx, ty)):
+            w = np.take(f, kk, axis=0)
+            w *= a
+            w *= b
+            v += w
+        return v
+
+    def at_pairs(self, x, y, p, m) -> np.ndarray:
+        """Same values as ``at(x, y)[p, m]`` for the point/site pairs ``(p, m)`` only."""
+        k, tx, ty = self._weights(x, y)
+        k, tx, ty = k[p], tx[p], ty[p]
+        ux, uy = 1 - tx, 1 - ty
+        f, nx = self._flat, self.nx
+        v = f[k, m] * ux
+        v *= uy
+        for kk, a, b in ((k + 1, tx, uy), (k + nx, ux, ty), (k + nx + 1, tx, ty)):
+            w = f[kk, m] * a
+            w *= b
+            v += w
+        return v
+
+
+class RadioMap:
+    """Place-tied part of the radio environment of one world."""
+
+    def __init__(self, layout: Layout, radio, seed: int):
+        self.layout, self.radio = layout, radio
+        self.is_grid = layout.is_grid
+        res = float(radio.map_res_m) if self.is_grid else max(float(radio.map_res_m), 2.0)
+        pad = 3.0 * res
+        self.res = res
+        self.x0, self.y0 = layout.xmin - pad, layout.ymin - pad
+        self.nx = int(np.ceil((layout.xmax - layout.xmin + 2 * pad) / res)) + 1
+        self.ny = int(np.ceil((layout.ymax - layout.ymin + 2 * pad) / res)) + 1
+        M = layout.n_sites
+        XX, YY = np.meshgrid(self.x0 + np.arange(self.nx) * res, self.y0 + np.arange(self.ny) * res)
+        rng_shadow, rng_los = streams(seed, "map", 2)
+
+        # nominal plan on a 2 m raster: nearest site (equal power and height, no buildings)
+        self.nres = 2.0
+        nnx = int((layout.xmax - layout.xmin + 2 * pad) / self.nres) + 2
+        nny = int((layout.ymax - layout.ymin + 2 * pad) / self.nres) + 2
+        NX, NY = np.meshgrid(self.x0 + np.arange(nnx) * self.nres, self.y0 + np.arange(nny) * self.nres)
+        nearest = cKDTree(layout.sites).query(np.c_[NX.ravel(), NY.ravel()])[1]
+        self.best_nominal = nearest.reshape(nny, nnx).astype(np.int16)
+
+        mask = layout.street_mask(XX, YY, margin=2.0 * res)
+        px, py = XX[mask], YY[mask]
+        P = len(px)
+        self.n_pix = P
+        self.idx = np.full((self.ny, self.nx), P, dtype=np.int64)    # pixel -> row; off-street -> dummy row P
+        self.idx[mask] = np.arange(P)
+        self.has_field = radio.place_share > 0.0
+        shadow = None
+        if self.has_field:
+            fres = min(2.0, radio.shadow_decorr_m / 4.0) if radio.shadow_decorr_m >= 4.0 else res
+            shadow = GaussianField(rng_shadow, layout, M, radio.shadow_decorr_m, max(fres, res),
+                                   radio.shadow_site_corr).at(px, py)
+            shadow *= np.float32(np.sqrt(radio.place_share))
+        self.los = None
+        self.los_share = float("nan")
+        self.gain = np.empty((P + 1, M), dtype=np.float32)            # last row: off-street dummy
+        gain = self.gain[:P]
+        if self.is_grid:
+            los = los_matrix(px, py, layout.sites, layout.buildings)
+            d2 = np.hypot(px[:, None] - layout.sites[None, :, 0], py[:, None] - layout.sites[None, :, 1])
+            if radio.clutter_los:
+                # spatially consistent LOS state; only links that the buildings leave clear need it
+                ip, im = np.nonzero(los)
+                lat = GaussianField(rng_los, layout, M, radio.los_corr_m, 5.0, 0.0).at_pairs(px, py, ip, im)
+                dd = d2[ip, im]
+                los[ip, im] = lat < ndtri(np.clip(p_los(dd, radio.pathloss), 1e-9, 1.0 - 1e-9))
+            gain[...] = path_loss(d2, los, radio.pathloss, radio.carrier_ghz, radio.bs_height_m,
+                                  radio.ue_height_m)
+            np.negative(gain, out=gain)
+            if shadow is not None:
+                shadow *= np.where(los, np.float32(radio.shadow_los_db), np.float32(radio.shadow_nlos_db))
+                gain += shadow
+            self.los = np.zeros((P + 1, M), dtype=bool)
+            self.los[:P] = los
+            self.los_share = float(los.mean())
+        elif shadow is not None:
+            gain[...] = shadow
+        else:
+            gain[...] = 0.0
+        self.gain[P] = FLOOR_DB if self.is_grid else 0.0
+
+    # ------------------------------------------------------------------
+    def _grid_coords(self, x, y):
+        gx = np.clip((np.asarray(x, dtype=float) - self.x0) / self.res, 0.0, self.nx - 1.001)
+        gy = np.clip((np.asarray(y, dtype=float) - self.y0) / self.res, 0.0, self.ny - 1.001)
+        return gx, gy
+
+    def lookup(self, x, y) -> np.ndarray:
+        """Bilinear interpolation of the static gain (or shadowing) map at points (P,) -> (P, M)."""
+        gx, gy = self._grid_coords(x, y)
+        ix, iy = gx.astype(np.int64), gy.astype(np.int64)
+        tx = (gx - ix).astype(np.float32)
+        ty = (gy - iy).astype(np.float32)
+        idx = self.idx
+        w = np.stack([(1 - tx) * (1 - ty), tx * (1 - ty), (1 - tx) * ty, tx * ty]).astype(np.float32)
+        p = np.stack([idx[iy, ix], idx[iy, ix + 1], idx[iy + 1, ix], idx[iy + 1, ix + 1]])
+        v = np.take(self.gain, p[0], axis=0) * w[0][:, None]
+        for q in (1, 2, 3):
+            v += np.take(self.gain, p[q], axis=0) * w[q][:, None]
+        return v
+
+    def los_at(self, x, y) -> np.ndarray:
+        """Line-of-sight state at points (nearest pixel) -> (P, M) bool (street grid only)."""
+        gx, gy = self._grid_coords(x, y)
+        return self.los[self.idx[np.rint(gy).astype(int), np.rint(gx).astype(int)]]
+
+    def nominal_cell(self, x, y) -> np.ndarray:
+        """Nominal best server (nearest site) at points of any shape."""
+        ny, nx = self.best_nominal.shape
+        ix = np.clip(np.rint((np.asarray(x) - self.x0) / self.nres).astype(int), 0, nx - 1)
+        iy = np.clip(np.rint((np.asarray(y) - self.y0) / self.nres).astype(int), 0, ny - 1)
+        return self.best_nominal[iy, ix]

handoverlab/channel/source.py

@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: MIT
+"""Received powers and L1 samples of a run, produced chunk by chunk.
+
+:class:`RadioSource` turns trajectories into received powers:
+
+* street grid: lookup of the place-tied radio map;
+* open area: path loss with a LOS state that is an AR(1) process along each
+  user's own path (nothing repeatable by place), plus the place-tied
+  shadowing field if any;
+* plus, if ``place_share < 1``, a shadowing process along each user's path;
+* plus a time-varying component (moving blockers), an AR(1) process updated
+  once per L1 period.
+
+It also draws the noisy L1 samples that feed the measurement filter.  Every
+random number of the radio part comes from here, so all rules run on the same
+world see identical samples.
+
+Antenna abstraction: each site forms a beam of gain ``bs_gain_db`` towards the
+user it serves and towards a user that measures it.  A site that serves other
+users interferes with the mean gain of its data beams (``isolation`` times the
+peak gain) scaled by its load.  No beam management and no fast fading.
+"""
+from __future__ import annotations
+
+from typing import Iterator
+
+import numpy as np
+from scipy.signal import lfilter
+from scipy.special import ndtri
+
+from ..seeds import streams
+from .pathloss import p_los, path_loss
+
+LN10_10 = np.log(10.0) / 10.0
+
+
+class Chunk:
+    """Radio samples of the consecutive steps ``k0 .. k0 + n - 1``.
+
+    ``rsrp`` (n, U, M) received power [dBm]; ``lin`` the same in mW; ``l1`` the
+    noisy L1 samples at the measurement instants (steps with ``k % mp == 0``).
+    """
+    __slots__ = ("k0", "n", "rsrp", "lin", "l1", "mp")
+
+    def __init__(self, k0, n, rsrp, lin, l1, mp):
+        self.k0, self.n, self.rsrp, self.lin, self.l1, self.mp = k0, n, rsrp, lin, l1, mp
+
+    @classmethod
+    def from_rsrp(cls, k0: int, rsrp: np.ndarray, mp: int, l1: np.ndarray = None) -> "Chunk":
+        """Chunk from given received powers (used by tests and custom radio sources)."""
+        rsrp = np.asarray(rsrp, dtype=float)
+        if l1 is None:
+            l1 = rsrp[::mp].copy()
+        return cls(k0, rsrp.shape[0], rsrp, np.exp(rsrp * LN10_10), l1, mp)
+
+
+def _ar1(w, r, z):
+    """Unit-variance AR(1) along axis 0 with coefficient ``r`` and previous value ``z``."""
+    y, _ = lfilter([np.sqrt(1.0 - r * r)], [1.0, -r], w, axis=0, zi=(r * z)[None])
+    return y
+
+
+class RadioSource:
+    """Received power of every site at every user and step."""
+
+    def __init__(self, world, chunk_steps: int = 1000):
+        sc = world.scenario
+        self.rmap = world.radio_map
+        self.X, self.Y, self.V = world.x, world.y, world.speed
+        self.S, self.U = self.X.shape
+        self.M = world.layout.n_sites
+        self.R = R = sc.radio
+        dt = sc.protocol.step_s
+        self.mp = max(1, int(round(sc.protocol.l1_period_s / dt)))
+        self.chunk = max(self.mp, (chunk_steps // self.mp) * self.mp)   # whole L1 periods per chunk
+        self.rng_t, self.rng_o, self.rng_m, self.rng_l = streams(world.seed, "radio", 4)
+        self.r_t = float(np.exp(-self.mp * dt / R.time_var_tau_s))     # per L1 period
+        self.zt = self.rng_t.standard_normal((self.U, self.M))         # stationary start
+        self.own = R.place_share < 1.0
+        self.r_o = np.exp(-self.V * dt / R.shadow_decorr_m)            # per user and step
+        self.zo = self.rng_o.standard_normal((self.U, self.M)) if self.own else None
+        self.open = not self.rmap.is_grid
+        if self.open:
+            self.r_l = np.exp(-self.V * dt / R.los_corr_m)
+            self.zl = self.rng_l.standard_normal((self.U, self.M))
+        self.p0 = R.tx_power_dbm + R.bs_gain_db + R.ue_gain_db
+
+    def _ar1_users(self, rng, r_u, z, n):
+        """AR(1) along time with one coefficient per user -> (n, U, M)."""
+        out = np.empty((n, self.U, self.M))
+        for u in range(self.U):
+            out[:, u, :] = _ar1(rng.standard_normal((n, self.M)), r_u[u], z[u])
+        return out
+
+    def chunks(self) -> Iterator[Chunk]:
+        """Yield :class:`Chunk` objects covering the whole run in order."""
+        R, rmap = self.R, self.rmap
+        sites = rmap.layout.sites
+        for k0 in range(0, self.S, self.chunk):
+            k1 = min(self.S, k0 + self.chunk)
+            n = k1 - k0
+            x = self.X[k0:k1].ravel()
+            y = self.Y[k0:k1].ravel()
+            shape = (n, self.U, self.M)
+            sig = None
+            if rmap.is_grid:
+                rs = rmap.lookup(x, y).astype(np.float64).reshape(shape)
+                if self.own:
+                    sig = np.where(rmap.los_at(x, y), R.shadow_los_db, R.shadow_nlos_db).reshape(shape)
+            else:
+                d2 = np.hypot(x[:, None] - sites[None, :, 0], y[:, None] - sites[None, :, 1])
+                g = self._ar1_users(self.rng_l, self.r_l, self.zl, n)
+                self.zl = g[-1].copy()
+                los = g.reshape(d2.shape) < ndtri(np.clip(p_los(d2, R.pathloss), 1e-9, 1.0 - 1e-9))
+                rs = -path_loss(d2, los, R.pathloss, R.carrier_ghz, R.bs_height_m, R.ue_height_m).reshape(shape)
+                sig = np.where(los, R.shadow_los_db, R.shadow_nlos_db).reshape(shape)
+                if rmap.has_field:
+                    rs += rmap.lookup(x, y).astype(np.float64).reshape(shape) * sig
+            if self.own:
+                o = self._ar1_users(self.rng_o, self.r_o, self.zo, n)
+                self.zo = o[-1].copy()
+                rs += np.sqrt(1.0 - R.place_share) * sig * o
+            nm = -(-n // self.mp)
+            if R.time_var_db > 0:
+                zt = _ar1(self.rng_t.standard_normal((nm, self.U, self.M)), self.r_t, self.zt)
+                self.zt = zt[-1].copy()
+                rs += R.time_var_db * np.repeat(zt, self.mp, axis=0)[:n]
+            rs += self.p0
+            l1 = rs[::self.mp] + R.l1_error_db * self.rng_m.standard_normal((nm, self.U, self.M))
+            yield Chunk(k0, n, rs, np.exp(rs * LN10_10), l1, self.mp)