openworld_radio_twin.torch_dataset#

A PyTorch dataset of the radio maps of a generated dataset or an extracted package.

The dataset code imports PyTorch only here; install it with the torch extra. One sample is one whole radio map with all its transmitters, or one transmitter of a radio map, as a dictionary of tensors on the grid of its radio arrays (rows south to north, columns west to east). Values are in physical units; nothing is normalised.

Classes

RadioMapDataset(root[, split, ...])

The radio maps listed in the index.parquet of root, one sample per radio map, or one per transmitter with per_transmitter.

RandomCrop(size)

Crop every entry of SPATIAL_KEYS of a sample to one random window of size cells.

class openworld_radio_twin.torch_dataset.RadioMapDataset(root, split=None, radio_map_ids=None, transform=None, per_transmitter=False)[source]#

Bases: Dataset

The radio maps listed in the index.parquet of root, one sample per radio map, or one per transmitter with per_transmitter.

root is a generated dataset, or a package whose scene archives are extracted into the package directory. The index is read with read_index(), which refuses a stale one. radio_map_ids keeps the listed radio maps, and an id that is not in the index raises KeyError. split then keeps those of one split of a package. A split that the package’s splits.json does not declare, and any split of an index without splits, as in a generated dataset, raise ValueError; a declared split with no radio maps gives an empty dataset. Both keep the index order. A radio map whose scene archive is not extracted raises FileNotFoundError. index holds the index rows of the selected radio maps, one per radio map, in index order. transform is applied to each sample.

A sample holds, with T transmitters and H by W cells:

  • geometry (float32, (3, H, W)): roof height above ground in metres (0 where there is no building), building footprint mask, and ground elevation in the scene frame in metres (the measurement cell centre minus the receiver height);

  • surface_classes (int64, (H, W)): the class of the terrain cell that holds the cell centre, NO_SURFACE_CLASS when the scene has no surface class grid;

  • indoor (bool, (H, W)): the receiver point lies inside a building;

  • tx_map (float32, (T, H, W)): 1 in the cell of each transmitter, all 0 for a transmitter off the grid; tx_cell (int64, (T, 2)): that cell’s row and column, which can lie outside the grid;

  • tx_position_m (float32, (T, 3)): east, north and up in the scene frame; tx_height_agl_m, tx_power_dbm, tx_azimuth_deg and tx_downtilt_deg (float32, (T,)); frequency_hz (float64 scalar);

  • path_gain_db, rss_dbm, sinr_db (float32, (T, H, W)): the values of load_radio_map(), 0 where coverage is false; coverage (bool, (T, H, W)): path gain, RSS and SINR are all positive;

  • serving_tx (int64, (H, W)): the serving transmitter, -1 where none serves;

  • radio_map_id (str).

With per_transmitter, a sample is one transmitter of a radio map: the radio maps in index order, and the transmitters of each in record order. The sample keeps the transmitter axis with T = 1, so every sample has one transmitter. It holds the entries above except sinr_db and serving_tx, which depend on the other transmitters of the radio map; coverage is where path gain and RSS are positive. It adds transmitter (int64 scalar), the transmitter’s index in the radio map. The sample reads the stored path gain of every transmitter of its radio map and unpacks only that transmitter’s.

class openworld_radio_twin.torch_dataset.RandomCrop(size)[source]#

Bases: object

Crop every entry of SPATIAL_KEYS of a sample to one random window of size cells.

size is an int for a square or (rows, columns). The window is drawn uniformly from PyTorch’s global random number generator, which the DataLoader seeds for each worker. The crop adds crop_origin (int64 (row, column) of the window’s first cell in the full radio map, accumulated over repeated crops) and shifts tx_cell to the window. Cropped entries are copies of the window, not views of the whole radio map. Every transmitter is kept; one outside the window has an all-zero tx_map. A size that is not one or two positive integers, and a radio map smaller than the window, raise ValueError.