Radio Maps
A radio map describes a metric, such as path gain, received signal strength (RSS), or signal-to-interference-plus-noise ratio (SINR) for a specific transmitter at every point on a measurement surface. In other words, for a given transmitter, it associates every point on a measurement surface with the channel gain, RSS, or SINR, that a receiver equipped with a dual-polarized isotropic antenna would observe at this point. A radio map is not uniquely defined as it depends on the transmit array and antenna pattern, the transmitter orientation, as well as the transmit precoding vector. Moreover, a radio map is not continuous but discrete because the measurement surface is quantized into small planar bins.
In Sionna, radio maps are generated using a radio map solver, which returns an instance of a specialized class derived from the abstract base class RadioMap
. The built-in radio map solver can compute a radio map for either of the following:
A rectangular measurement plane grid, subdivided into equal-sized rectangular cells. In this case, an instance of
PlanarRadioMap
is returned.A mesh, where each triangle of the mesh serves as a bin of the radio map. Here, an instance of
MeshRadioMap
is returned.
Radio maps can be visualized by passing them as arguments to the functions render()
, render_to_file()
, or preview()
. Additionally, PlanarRadioMap
features a class method show()
.
A very useful feature is sample_positions()
which allows sampling
of random positions within the scene that have sufficient path gain, RSS, or SINR from a specific transmitter.
- class sionna.rt.PlanarRadioMap(scene, cell_size, center=None, orientation=None, size=None)[source]
Planar Radio Map
A planar radio map is defined by a measurement grid, i.e., a rectangular grid of cells. It is computed by a radio map solver.
- Parameters:
scene (
sionna.rt.scene.Scene
) – Scene for which the radio map is computedcenter (
typing.Optional
[mitsuba.Point3f
]) – Center of the radio map [m] as three-dimensional vectororientation (
typing.Optional
[mitsuba.Point3f
]) – Orientation of the radio map specified through three angles corresponding to a 3D rotation as defined in (3)size (
typing.Optional
[mitsuba.Point2f
]) – Size of the radio map [m]cell_size (
mitsuba.Point2f
) – Size of a cell of the radio map [m]
- property cell_centers
Positions of the centers of the cells in the global coordinate system
- Type:
mi.TensorXf [cells_per_dim_y, cells_per_dim_x, 3]
- property cell_size
Size of a cell of the radio map [m]
- Type:
mi.Point2f
- property cells_count
Total number of cells
- Type:
int
- property cells_per_dim
Number of cells per dimension
- Type:
mi.Point2u
- property center
Center of the radio map in the global coordinate system
- Type:
mi.Point3f
- property measurement_surface
Mitsuba rectangle corresponding to the radio map measurement surface
- Type:
mi.Rectangle
- property orientation
Orientation of the radio map
specified through three angles corresponding to a 3D rotation as defined in (3). An orientation of corresponds to a radio map that is parallel to the XY plane.- Type:
mi.Point3f
- property path_gain
Path gains across the radio map from all transmitters
- Type:
mi.TensorXf [num_tx, cells_per_dim_y, cells_per_dim_x]
- property rx_cell_indices
Computes and returns the cell index positions corresponding to receivers in the format (column, row)
- Type:
mi.Point2u
- sample_positions(num_pos, metric='path_gain', min_val_db=None, max_val_db=None, min_dist=None, max_dist=None, tx_association=True, center_pos=False, seed=1)[source]
Samples random user positions in a scene based on a radio map
For a given radio map,
num_pos
random positions are sampled around each transmitter, such that the selected metric, e.g., SINR, is larger thanmin_val_db
and/or smaller thanmax_val_db
. Similarly,min_dist
andmax_dist
define the minimum and maximum distance of the random positions to the transmitter under consideration. By activating the flagtx_association
, only positions are sampled for which the selected metric is the highest across all transmitters. This is useful if one wants to ensure, e.g., that the sampled positions for each transmitter provide the highest SINR or RSS.Note that due to the quantization of the radio map into cells it is not guaranteed that all above parameters are exactly fulfilled for a returned position. This stems from the fact that every individual cell of the radio map describes the expected average behavior of the surface within this cell. For instance, it may happen that half of the selected cell is shadowed and, thus, no path to the transmitter exists but the average path gain is still larger than the given threshold. Please enable the flag
center_pos
to sample only positions from the cell centers.import numpy as np import sionna from sionna.rt import load_scene, PlanarArray, Transmitter,\ RadioMapSolver, Receiver scene = load_scene(sionna.rt.scene.munich) # Configure antenna array for all transmitters scene.tx_array = PlanarArray(num_rows=1, num_cols=1, vertical_spacing=0.7, horizontal_spacing=0.5, pattern="iso", polarization="V") # Add a transmitters tx = Transmitter(name="tx", position=[-195,-240,30], orientation=[0,0,0]) scene.add(tx) solver = RadioMapSolver() rm = solver(scene, cell_size=(1., 1.), samples_per_tx=100000000) positions,_ = rm.sample_positions(num_pos=200, min_val_db=-100., min_dist=50., max_dist=80.) positions = positions.numpy() positions = np.squeeze(positions, axis=0) for i,p in enumerate(positions): rx = Receiver(name=f"rx-{i}", position=p, orientation=[0,0,0]) scene.add(rx) scene.preview(clip_at=10.);
The above example shows an example for random positions between 50m and 80m from the transmitter and a minimum path gain of -100 dB. Keep in mind that the transmitter can have a different height than the radio map which also contributes to this distance. For example if the transmitter is located 20m above the surface of the radio map and a
min_dist
of 20m is selected, also positions directly below the transmitter are sampled.- Parameters:
num_pos (
int
) – Number of returned random positions for each transmittermetric ("path_gain" | "rss" | "sinr") – Metric to be considered for sampling positions
min_val_db (
typing.Optional
[float
]) – Minimum value for the selected metric ([dB] for path gain and SINR; [dBm] for RSS). Positions are only sampled from cells where the selected metric is larger than or equal to this value. Ignored if None.max_val_db (
typing.Optional
[float
]) – Maximum value for the selected metric ([dB] for path gain and SINR; [dBm] for RSS). Positions are only sampled from cells where the selected metric is smaller than or equal to this value. Ignored if None.min_dist (
typing.Optional
[float
]) – Minimum distance [m] from transmitter for all random positions. Ignored if None.max_dist (
typing.Optional
[float
]) – Maximum distance [m] from transmitter for all random positions. Ignored if None.tx_association (
bool
) – If True, only positions associated with a transmitter are chosen, i.e., positions where the chosen metric is the highest among all all transmitters. Else, a user located in a sampled position for a specific transmitter may perceive a higher metric from another TX.center_pos (
bool
) – If True, all returned positions are sampled from the cell center (i.e., the grid of the radio map). Otherwise, the positions are randomly drawn from the surface of the cell.seed (int)
- Return type:
typing.Tuple
[drjit.cuda.ad.TensorXf
,drjit.cuda.ad.TensorXu
]- Returns:
Random positions
[m] (shape :[num_tx, num_pos, 3]
) that are in cells fulfilling the configured constraints- Returns:
Cell indices (shape
[num_tx, num_pos, 2]
) corresponding to the random positions in the format (column, row)
- show(metric='path_gain', tx=None, vmin=None, vmax=None, show_tx=True, show_rx=False)[source]
Visualizes a radio map
The position of the transmitters is indicated by “+” markers. The positions of the receivers are indicated by “x” markers.
- Parameters:
metric ("path_gain" | "rss" | "sinr") – Metric to show
tx (
typing.Optional
[int
]) – Index of the transmitter for which to show the radio map. If None, the maximum value over all transmitters for each cell is shown.vmin (
typing.Optional
[float
]) – Defines the minimum value [dB] for the colormap covers. If set to None, then the minimum value across all cells is used.vmax (
typing.Optional
[float
]) – Defines the maximum value [dB] for the colormap covers. If set to None, then the maximum value across all cells is used.show_tx (
bool
) – If set to True, then the position of the transmitters are shown.show_rx (
bool
) – If set to True, then the position of the receivers are shown.
- Return type:
matplotlib.figure.Figure
- Returns:
Figure showing the radio map
- show_association(metric='path_gain', show_tx=True, show_rx=False, color_map=None)[source]
Visualizes cell-to-tx association for a given metric
The positions of the transmitters and receivers are indicated by “+” and “x” markers, respectively.
- Parameters:
metric ("path_gain" | "rss" | "sinr") – Metric to show
show_tx (
bool
) – If set to True, then the position of the transmitters are shown.show_rx (
bool
) – If set to True, then the position of the receivers are shown.color_map (
typing.Union
[str
,numpy.ndarray
,None
]) – Either the name of a Matplotlib colormap or a NumPy array of shape (num_tx, 3) containing the RGB values for the colors of the transmitters. If None, a default color map with the right number of colors is generated.
- Return type:
matplotlib.figure.Figure
- Returns:
Figure showing the cell-to-transmitter association
- property size
Size of the radio map [m]
- Type:
mi.Point2f
- tx_association(metric='path_gain')[source]
Computes cell-to-transmitter association
Each cell is associated with the transmitter providing the highest metric, such as path gain, received signal strength (RSS), or SINR.
- Parameters:
metric ("path_gain" | "rss" | "sinr") – Metric to be used
- Return type:
drjit.cuda.ad.TensorXi
- Returns:
Cell-to-transmitter association
- property tx_cell_indices
Cell index position of each transmitter in the format (column, row)
- Type:
mi.Point2u
- class sionna.rt.MeshRadioMap(scene, meas_surface)[source]
Mesh Radio Map
A mesh-based radio map is computed by a radio map solver for a measurement surface defined by a mesh. Each triangle of the mesh serves as a bin of the radio map.
- Parameters:
scene (
sionna.rt.scene.Scene
) – Scene for which the radio map is computedmeas_surface (
mitsuba.Mesh
) – Mesh to be used as the measurement surface
- property cell_centers
Positions of the centers of the cells in the global coordinate system
- Type:
mi.Point3f [cells_count, 3]
- property cells_count
Total number of cells in the radio map
- Type:
int
- property measurement_surface
Mitsuba shape corresponding to the radio map measurement surface
- Type:
mi.Mesh
- property path_gain
Path gains across the radio map from all transmitters
- Type:
mi.TensorXf [num_tx, num_primitives]
- sample_positions(num_pos, metric='path_gain', min_val_db=None, max_val_db=None, min_dist=None, max_dist=None, tx_association=True, center_pos=False, seed=1)[source]
Samples random user positions in a scene based on a radio map
For a given radio map,
num_pos
random positions are sampled around each transmitter, such that the selected metric, e.g., SINR, is larger thanmin_val_db
and/or smaller thanmax_val_db
. Similarly,min_dist
andmax_dist
define the minimum and maximum distance of the random positions to the transmitter under consideration. By activating the flagtx_association
, only positions are sampled for which the selected metric is the highest across all transmitters. This is useful if one wants to ensure, e.g., that the sampled positions for each transmitter provide the highest SINR or RSS.Note that due to the quantization of the radio map into cells it is not guaranteed that all above parameters are exactly fulfilled for a returned position. This stems from the fact that every individual cell of the radio map describes the expected average behavior of the surface within this cell. For instance, it may happen that half of the selected cell is shadowed and, thus, no path to the transmitter exists but the average path gain is still larger than the given threshold. Please enable the flag
center_pos
to sample only positions from the cell centers.import numpy as np import sionna from sionna.rt import load_scene, PlanarArray, Transmitter, \ RadioMapSolver, Receiver, transform_mesh scene = load_scene(sionna.rt.scene.san_francisco) # Configure antenna array for all transmitters scene.tx_array = PlanarArray(num_rows=1, num_cols=1, vertical_spacing=0.7, horizontal_spacing=0.5, pattern="iso", polarization="V") # Add a transmitters tx = Transmitter(name="tx", position=[15.9,121.2,25], orientation=[0,0,0], display_radius=2.0) scene.add(tx) # Create a measurement surface by cloning the terrain # and elevating it by 1.5 meters measurement_surface = scene.objects["Terrain"].clone(as_mesh=True) transform_mesh(measurement_surface, translation=[0,0,1.5]) solver = RadioMapSolver() rm = solver(scene, cell_size=(1., 1.), measurement_surface=measurement_surface, samples_per_tx=100000000) positions,_ = rm.sample_positions(num_pos=200, min_val_db=-100., min_dist=50., max_dist=80.) positions = positions.numpy() positions = np.squeeze(positions, axis=0) for i,p in enumerate(positions): rx = Receiver(name=f"rx-{i}", position=p, orientation=[0,0,0], display_radius=2.0) scene.add(rx) scene.preview();
The above example shows an example for random positions between 50m and 80m from the transmitter and a minimum path gain of -100 dB. Keep in mind that the transmitter can have a different height than the radio map which also contributes to this distance. For example if the transmitter is located 20m above the surface of the radio map and a
min_dist
of 20m is selected, also positions directly below the transmitter are sampled.- Parameters:
num_pos (
int
) – Number of returned random positions for each transmittermetric ("path_gain" | "rss" | "sinr") – Metric to be considered for sampling positions
min_val_db (
typing.Optional
[float
]) – Minimum value for the selected metric ([dB] for path gain and SINR; [dBm] for RSS). Positions are only sampled from cells where the selected metric is larger than or equal to this value. Ignored if None.max_val_db (
typing.Optional
[float
]) – Maximum value for the selected metric ([dB] for path gain and SINR; [dBm] for RSS). Positions are only sampled from cells where the selected metric is smaller than or equal to this value. Ignored if None.min_dist (
typing.Optional
[float
]) – Minimum distance [m] from transmitter for all random positions. Ignored if None.max_dist (
typing.Optional
[float
]) – Maximum distance [m] from transmitter for all random positions. Ignored if None.tx_association (
bool
) – If True, only positions associated with a transmitter are chosen, i.e., positions where the chosen metric is the highest among all all transmitters. Else, a user located in a sampled position for a specific transmitter may perceive a higher metric from another TX.center_pos (
bool
) – If True, all returned positions are sampled from the cell center (i.e., the grid of the radio map). Otherwise, the positions are randomly drawn from the surface of the cell.seed (int)
- Return type:
typing.Tuple
[drjit.cuda.ad.TensorXf
,drjit.cuda.ad.TensorXu
]- Returns:
Random positions
[m] (shape :[num_tx, num_pos, 3]
) that are in cells fulfilling the configured constraints- Returns:
Cell indices (shape
[num_tx, num_pos]
) corresponding to the random positions
- class sionna.rt.RadioMap(scene)[source]
Abstract base class for radio maps
A radio map is generated for the loaded scene for all transmitters using a radio map solver. Please refer to the documentation of this module for further details.
- Parameters:
scene (
sionna.rt.scene.Scene
) – Scene for which the radio map is computed
- cdf(metric='path_gain', tx=None, bins=200)[source]
Computes and visualizes the CDF of a metric of the radio map
- Parameters:
metric ("path_gain" | "rss" | "sinr") – Metric to be shown
tx (
typing.Optional
[int
]) – Index or name of the transmitter for which to show the radio map. If None, the maximum value over all transmitters for each cell is shown.bins (
int
) – Number of bins used to compute the CDF
- Return type:
typing.Tuple
[matplotlib.figure.Figure
,drjit.cuda.ad.TensorXf
,drjit.cuda.ad.Float
]- Returns:
Figure showing the CDF
- Returns:
Data points for the chosen metric
- Returns:
Cummulative probabilities for the data points
- abstract property cell_centers
Positions of the centers of the cells in the global coordinate system.
The type of this property depends on the subclass.
- abstract property cells_count
Total number of cells in the radio map
- Type:
int
- abstract property measurement_surface
Mitsuba rectangle corresponding to the radio map measurement plane
- Type:
mi.Shape
- property num_rx
Number of receivers
- Type:
int
- property num_tx
Number of transmitters
- Type:
int
- abstract property path_gain
Path gains across the radio map from all transmitters
The shape of the tensor depends on the subclass.
- Type:
mi.TensorXf
with shape [num_tx, …], where the specific dimensions are defined by the subclass.
- property rss
Received signal strength (RSS) across the radio map from all transmitters
The shape of the tensor depends on the subclass.
- Type:
mi.TensorXf
with shape [num_tx, …], where the specific dimensions are defined by the subclass.
- sample_cells(num_cells, metric='path_gain', min_val_db=None, max_val_db=None, min_dist=None, max_dist=None, tx_association=True, seed=1)[source]
Samples random cells in a radio map
For a given radio map,
num_cells
random cells are sampled such that the selected metric, e.g., SINR, is larger thanmin_val_db
and/or smaller thanmax_val_db
. Similarly,min_dist
andmax_dist
define the minimum and maximum distance of the random cells centers to the transmitter under consideration. By activating the flagtx_association
, only cells for which the selected metric is the highest across all transmitters are sampled. This is useful if one wants to ensure, e.g., that the sampled cells for each transmitter provide the highest SINR or RSS.- Parameters:
num_cells (
int
) – Number of returned random cells for each transmittermetric ("path_gain" | "rss" | "sinr") – Metric to be considered for sampling cells
min_val_db (
typing.Optional
[float
]) – Minimum value for the selected metric ([dB] for path gain and SINR; [dBm] for RSS). Only cells for which the selected metric is larger than or equal to this value are sampled. Ignored if None.max_val_db (
typing.Optional
[float
]) – Maximum value for the selected metric ([dB] for path gain and SINR; [dBm] for RSS). Only cells for which the selected metric is smaller than or equal to this value are sampled. Ignored if None.min_dist (
typing.Optional
[float
]) – Minimum distance [m] from transmitter for all random cells. Ignored if None.max_dist (
typing.Optional
[float
]) – Maximum distance [m] from transmitter for all random cells. Ignored if None.tx_association (
bool
) – If True, only cells associated with a transmitter are chosen, i.e., cells where the chosen metric is the highest among all all transmitters. Else, a user located in a sampled cell for a specific transmitter may perceive a higher metric from another TX.seed (
int
) – Seed for the random number generator
- Return type:
typing.Tuple
[drjit.cuda.ad.TensorXu
]- Returns:
Cell indices (shape
[num_tx, num_cells]
) corresponding to the random cells
- property sinr
SINR across the radio map from all transmitters
The shape of the tensor depends on the subclass.
- Type:
mi.TensorXf
with shape [num_tx, …], where the specific dimensions are defined by the subclass.
- transmitter_radio_map(metric='path_gain', tx=None)[source]
Returns the radio map values corresponding to transmitter
tx
and a specificmetric
If
tx
is None, then returns for each cell the maximum value accross the transmitters.- Parameters:
metric ("path_gain" | "rss" | "sinr") – Metric for which to return the radio map
tx (int | None)
- Return type:
drjit.cuda.ad.TensorXf
- tx_association(metric='path_gain')[source]
Computes cell-to-transmitter association.
Each cell is associated with the transmitter providing the highest metric, such as path gain, received signal strength (RSS), or SINR.
- Parameters:
metric ("path_gain" | "rss" | "sinr") – Metric to be used
- Return type:
drjit.cuda.ad.TensorXi
- Returns:
Cell-to-transmitter association. The value -1 indicates that there is no coverage for the cell.