Radio-map files

Radio maps from a file (radio.map_file, since 1.12.0): format, reading, writing, and building a map from a ray-tracer raster or from measured points.

handoverlab.mapfile

Radio maps from a file: ray tracing or measurements (radio.map_file; since 1.12.0).

TR 38.901 V19.5.0 clause 8 (map-based hybrid channel model) creates the channel from deterministic ray tracing on a digitized map plus stochastic components; it is "not calibrated and can be used per company basis", and the format of the map is left to the implementation. HandoverLab takes the deterministic large-scale part from such a map: the path gain of every site at every pixel [dB], without transmit power and antenna gains (HandoverLab adds those, or the beams). The small-scale part is not modelled, as everywhere in HandoverLab.

File format (.npz, format "handoverlab-radiomap", version 1):

========= ================= =========================================================================== key shape / type meaning ========= ================= =========================================================================== format str "handoverlab-radiomap" version int 1 x0, y0 float coordinates of the centre of pixel [0, 0] [m] res float pixel size [m] idx (ny, nx) int32 row of gain_db for every pixel, -1 where there is no value gain_db (P, M) float32 path gain of every site [dB] (negative), one row per pixel with a value los (P, M) bool optional: line of sight (sets the shadowing standard deviation of the part of the shadowing that moves with the user, radio.place_share < 1) sites (M, 2) float64 site positions [m]; must equal those of the scenario's layout source str free text: where the map comes from ========= ================= ===========================================================================

Pixel (iy, ix) has its centre at (x0 + ix * res, y0 + iy * res); values between pixel centres are interpolated bilinearly. Users must stay where there are values: on the street grid in the streets, in the open area and the indoor hall everywhere in the area.

MapFileError

Bases: ValueError

A radio-map file that cannot be used.

file_sha256(path: str) -> str

SHA-256 of a file (stored with the scenario so that a changed map is noticed).

save_map(path: str, x0: float, y0: float, res: float, idx: np.ndarray, gain_db: np.ndarray, sites: np.ndarray, los: Optional[np.ndarray] = None, source: str = '') -> str

Write a radio-map file (see the module text) and return its path.

load_map(path: str) -> Dict[str, object]

Read and check a radio-map file; returns its arrays as a dictionary.

export_map(rmap, path: str, source: str = '') -> str

Write the radio map of a street-grid world (world.radio_map) as a file.

Importing it again (radio.map_file) gives the same received powers bit for bit, so a run gives the same event log; the open area draws its LOS state along each user's path and has no static map.

map_from_raster(path: str, x0: float, y0: float, res: float, gain_db: np.ndarray, sites: np.ndarray, valid: Optional[np.ndarray] = None, los: Optional[np.ndarray] = None, source: str = '') -> str

Write a map from a full raster gain_db (ny, nx, M), e.g. the path-gain map of a ray tracer.

valid (ny, nx) marks the pixels with a value (default: all finite values).

map_from_points(path: str, x: np.ndarray, y: np.ndarray, gain_db: np.ndarray, sites: np.ndarray, area, res: float = 2.0, holdout: float = 0.1, seed: int = 1, source: str = '')

Interpolate measured path gains (points x, y with gain_db (N, M)) onto a raster and write the map.

area is (xmin, xmax, ymin, ymax). Linear interpolation per site (SciPy griddata), nearest value outside the convex hull of the points. A share holdout of the points is left out first and the interpolation error on them is returned: (path, {"rmse_db", "mae_db", "n_holdout"}); the map itself is then built from all points.