Configuration

Scenarios, experiments and their validation; every key of the user guide's tables is a field here.

handoverlab.config

Scenario and experiment configuration.

A scenario (the simulated world and the protocol constants) is a tree of dataclasses. It can be built in Python, or read from a YAML, TOML or JSON file, or from a plain dictionary. Every key is checked: an unknown key or a value of the wrong type raises ConfigError with the full key name.

An experiment adds the seeds, the handover rules to compare and the output file to a scenario; it is what the command line runs::

schema: 1                  # file format version (optional; see docs/stability.md)
scenario:
  layout: {kind: street_grid, blocks: [3, 3], site_spacing_m: 100}
  mobility: {users: 40, profile: veh16}
  run: {duration_s: 120, warmup_s: 20}
seeds: [1, 2]
rules:
  - {rule: a3, off_db: 3.0, ttt_s: 0.16}
  - {rule: cho, o_prep_db: -2.0, o_exec_db: 3.0}
output: results/metrics.csv

ConfigError

Bases: ValueError

Invalid configuration; the message names the offending key.

LayoutConfig dataclass

Deployment geometry.

street_grid is the urban grid of 3GPP TR 37.885 Annex A: blocks of pitch_m (433 m x 250 m between street centre lines), streets street_width_m wide. The default of 3 x 3 blocks is the minimum area of TR 37.885 Table A-1. Sites stand on the pavement every site_spacing_m metres, site_offset_m from the street centre line.

open_area is the same rectangle without buildings, with sites on a hexagonal grid of spacing site_spacing_m.

highway (since 1.0.0rc3) is the straight multi-lane road of the TR 37.885 highway case: lanes lanes of lane_width_m per direction over road_length_m, without buildings; roadside sites every site_spacing_m metres, site_offset_m beyond the road edge, alternately on the two sides.

indoor (since 1.7.0) is the indoor office of TR 38.901 Table 7.2-2: a hall of 120 m x 50 m without walls and ceiling sites on a rectangular grid of spacing site_spacing_m (20 m in the standard).

area_m (since 1.7.0) sets the width and height of the rectangle of open_area and indoor [m]; unset, open_area takes the size of the street grid and indoor 120 m x 50 m. min_site_distance_m (since 1.7.0) is the minimum 2D distance of a user's start and waypoints from every site in open_area and indoor (TR 38.901 Table 7.2-3, RMa: 35 m); the straight legs between them may pass closer.

wrap (since 1.11.0, highway only) applies the wrap-around of TR 37.885 Table A-1: a vehicle keeps its lane and direction and re-enters the road at the other end, and every distance and angle between a user and a site is taken to the nearest image of the site along the road (period road_length_m); the place-tied shadowing field is periodic along the road. Without it (the default) a vehicle turns at the end of the road.

sites_file (since 1.0.0rc3) names a CSV file with the columns x and y [m]; it is read when the scenario is loaded and fills sites.

size_m: Tuple[float, float] property

Width and height of the simulated rectangle [m].

BeamConfig dataclass

SSB beams, beam management and beam failure recovery of one layer (optional, since 1.10.0).

Every site carries sectors panels (cells); boresight of sector s at sector_az0_deg + s * 360 / sectors degrees. A panel is a uniform rectangular array of panel = (M, N) single-polarised elements at half a wavelength (TR 38.901 clause 7.3) with the element pattern of Table 7.3-1; each of the n_ssb SSB beams has DFT weights that steer it to the zenith angle tilt_deg (Eq. 7.3-1) and to one of n_ssb azimuths spread evenly over beam_span_deg (default: the sector width). The cell quality follows TS 38.331 clause 5.5.3.3 (ssb_avg = nrofSS-BlocksToAverage, ssb_thresh_dbm = absThreshSS-BlocksConsolidation; unset: the highest beam).

Beam management: the gNB moves the serving beam (TCI state) to the best reported SSB beam when it is switch_db better than the serving beam in a periodic L1-RSRP report (every report_s), tci_delay_s later.

Beam failure detection and recovery (bfd; TS 38.213 clause 6, TS 38.321 clause 5.17, TS 38.133 clause 8.5): the BFD reference signal is the SSB of the serving beam (an SSB in q0, as TS 38.133 8.5.1 allows); a beam failure instance is indicated when its quality, averaged over the evaluation period of TS 38.133 Table 8.5.2.2-1/-2, is below Qout_LR (10 % BLER of a hypothetical PDCCH at 0 dB to the SSS, TS 38.133 Table 8.5.2.1-1; protocol.qout_db + 4 dB in SSB SINR, as Qout has +4 dB, Table 8.1.2.1-1; since 2.1.0); bfi_max = beamFailureInstanceMaxCount, bfd_timer = beamFailureDetectionTimer in indication periods (pbfdN); then random access on the SpCell: contention-free on the best candidate SSB with L1-RSRP above rsrp_thresh_ssb_dbm (rsrp-ThresholdSSB) while bfr_timer_s (beamFailureRecoveryTimer) runs, otherwise contention-based; one preamble attempt takes ra_attempt_s (two for contention-based access) and succeeds if the chosen beam's SINR is at least Qout; after preamble_max (preambleTransMax) failed attempts a random-access problem is a radio-link failure (TS 38.331 clause 5.3.10.3). rlm_rs sets the RLM reference signals: "tci" the serving beam (TS 38.331 RadioLinkMonitoringConfig: no RS configured), "beams" the N_RLM best beams of the last report (TS 38.133 Table 8.1.1-2). rx_sweep_n is the scaling factor N of TS 38.133 (unset: 1 in FR1 and FR3, 8 in FR2-1, 12 in FR2-2).

LayerConfig dataclass

A further carrier and its cells (optional, since 1.10.0; see RadioConfig.layers).

Unset values are taken from the scenario's radio (carrier, link budget, propagation) and layout (site placement). cosited puts the layer on the sites of the first layer with the same LOS states, shadowing and blockers (TR 38.901 clause 7.6.5; with radio.channel_detail "3gpp" such a layer must not change pathloss, los_corr_m or shadow_decorr_m, since 2.1.0); otherwise the layer has its own sites (sites, sites_file or site_spacing_m / site_offset_m) and independent random fields.

RadioConfig dataclass

Carrier, link budget, propagation and the antenna abstraction (TR 38.901).

beams (since 1.10.0) replaces the antenna abstraction by sectors with SSB beams (BeamConfig); layers (since 1.10.0) adds carriers with their own cells (LayerConfig). With either of them the measurements are SS-RSRP per resource element (the power over the bandwidth minus 10 log10(bandwidth / scs_khz)); scs_khz unset is 30 kHz below 7.125 GHz and 120 kHz above.

channel_detail (since 2.1.0) selects how closely the large-scale channel follows TR 38.901 V19.5.0:

  • "3gpp" (the default): the place-tied shadowing and LOS fields have the exponential autocorrelation exp(-d / d_cor) of Eq. (7.4-5) (clause 7.4.4; clause 7.6.3.1 for the LOS state), the shadowing of different sites is uncorrelated unless shadow_site_corr is set (clause 7.5, step 4), the UMa LOS probability has the factor C'(h_UT) of Table 7.4.2-1 and the UMa path loss the random effective environment height h_E of Table 7.4.1-1 note 1 (both matter only for h_UT >= 13 m), a co-sited layer must keep the LOS-state and shadowing settings of the first layer (clause 7.6.5), the antenna heights must lie in the applicability ranges of Table 7.4.1-1, and an NTN satellite takes the tabled 3 dB beamwidth of TR 38.821 Tables 6.1.1.1-1/-2 (Table 6.1.1.1-4);
  • "simple": the model of 2.0.0 and 1.x (Gaussian-shaped field correlation exp(-(d / d_cor)^2), shadowing 0.5-correlated between sites, no C'(h_UT), h_E = 1 m, no checks of the heights or of co-sited layers, the beamwidth computed from the aperture).

shadow_site_corr unset (None, since 2.1.0) is 0 with "3gpp" and 0.5 with "simple".

extended: bool property

True if beams or further layers are configured (the extended radio model of 1.10.0).

noise_dbm: float property

Thermal noise over the carrier plus the noise figure [dBm].

ProtocolConfig dataclass

Measurement chain, handover timing and the failure model.

Defaults follow 3GPP TR 36.839 / TR 36.842 (Qout -8 dB, Qin -6 dB, T310 1 s, N310 = N311 = 1, preparation 50 ms, execution 40 ms) and the L3 filter of TS 38.331 clause 5.5.3.2.

Service dataclass

A service class (5QI of TS 23.501 Table 5.7.4-1) and its label thresholds.

TrafficConfig dataclass

Services, background load and the scheduler abstraction.

SpeedGroup dataclass

A share of users with a uniform speed range and lateral displacement range.

MobilityConfig dataclass

Number of users and their speeds; groups overrides the named profile.

RunConfig dataclass

Length of a run and (since 1.11.0) the backend of the step loop.

backend "numpy" (the default and the reference) or "numba": a compiled kernel for the radio-link monitoring of every step (handoverlab.engine._kernels; needs pip install handoverlab[fast]). Both give bit-identical results, so the backend is not part of the job IDs.

NtnConfig dataclass

One LEO satellite with earth-moving beams, for layout.kind: ntn (since 2.0.0; see handoverlab.channel.ntn).

Defaults: LEO-600, Set-1 satellite parameters in the S band of TR 38.821 Table 6.1.1.1-1 (equivalent aperture 2 m, EIRP density 34 dBW/MHz), 19 beams on the UV plane (Table 6.1.1.1-4), the central beam pointing at the area centre with 30 degrees elevation (case 2; the target elevation of the LEO link budget, Table 6.1.3.2-1), the rural tables of TR 38.811, the atmospheric zenith attenuation of the link budget of Table 6.1.3.3-1 through Eq. 6.6-8 and the ionospheric scintillation loss of 2.2 dB (Table 6.1.3.2-1, note 1).

hpbw_deg (since 2.1.0) is the 3 dB beamwidth from which the adjacent beam spacing sqrt(3) sin(HPBW / 2) is computed and to which the Bessel pattern is scaled (TR 38.821 Table 6.1.1.1-4: "Only the 3dB beam width parameters should be used"). Unset, it is the tabled width of TR 38.821 Tables 6.1.1.1-1 and -2 for the S-band apertures of 2 m (4.4127 degrees) and 1 m (8.8320 degrees) at 2 GHz with radio.channel_detail "3gpp", and otherwise the 3 dB width of the Bessel pattern of the aperture (the model of 2.0.0).

los_model (since 2.1.0): "probability" draws the LOS state from the LOS probability of TR 38.811 Table 6.6.1-1 (NLOS links get the clutter loss and the NLOS shadowing of Tables 6.6.2-1..3); "los" makes every link LOS, the baseline propagation condition of TR 38.821 Table 6.1.1.1-5 ("Clear Sky, Line of sight"), which Table 6.1.1.1-7 keeps for the performance evaluation.

Scenario dataclass

One simulated condition. Together with a seed it fixes a world.

to_dict(full: bool = False) -> Dict[str, Any]

The scenario as a plain dictionary.

Keys added after 1.0.0rc2 (LATE_KEYS) are left out while they have their default value, so that the job IDs and study locks of scenarios that do not use them stay as they were; full=True keeps every key.

from_dict(data: Union[Dict[str, Any], str]) -> 'Scenario' classmethod

Scenario from a dictionary.

data may also be the name of a built-in scenario, or contain the key base with such a name; the other values then change the built-in scenario (see handoverlab.scenarios).

with_overrides(overrides: Dict[str, Any]) -> 'Scenario'

Copy with changed values; keys are dotted paths such as "layout.site_spacing_m".

validate() -> None

Range checks that name the offending key.

read_sites(path: Union[str, os.PathLike]) -> Tuple[Tuple[float, float], ...]

Site positions from a CSV file with a header row and the columns x and y [m].

Other columns are ignored. A relative path is taken from the current directory.

read_file(path: Union[str, os.PathLike]) -> Dict[str, Any]

Read a YAML (.yaml/.yml), TOML (.toml) or JSON (.json) file into a dictionary.

load_config(source: Union[str, os.PathLike, Dict[str, Any]]) -> Experiment

Experiment from a file path or a dictionary.