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 surfacewith 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 aradio map solver, which returns an instance of a specialized class derived from the abstract base classRadioMap. 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 ofPlanarRadioMap is returned.

• A mesh, where each triangle of the mesh serves as a bin of the radio map. Here, an instance ofMeshRadioMap is returned.

Radio maps can be visualized by passing them as arguments to the functionsrender(),render_to_file(), orpreview(). Additionally,PlanarRadioMap features a class methodshow().

A very useful feature issample_positions() which allows samplingof random positions within the scene that have sufficient path gain, RSS, or SINR from a specific transmitter.

classsionna.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 rectangulargrid of cells. It is computed byaradio map solver.

Parameters:

• scene (sionna.rt.scene.Scene) – Scene for which the radio map is computed

• center (typing.Optional[mitsuba.Point3f]) – Center of the radio map\((x,y,z)\) [m] asthree-dimensional vector

• orientation (typing.Optional[mitsuba.Point3f]) – Orientation of the radio map\((\alpha, \beta, \gamma)\) specified through three anglescorresponding 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]

add_paths(e_fields,array_w,si,k_world,tx_indices,active,diffracted_paths,solid_angle=None,tx_positions=None,wedges=None,diff_point=None,wedges_samples_cnt=None)[source]

Adds the contribution of the paths that hit the measurement surfaceto the radio maps

The radio maps are updated in place.

Parameters:

• e_fields (mitsuba.Vector4f) – Electric fields as real-valued vectors of dimension 4

• array_w (typing.List[drjit.cuda.ad.Float]) – Weighting used to model the effect of the transmitterarray

• si (mitsuba.SurfaceInteraction3f) – Informations about the interaction with the measurementsurface

• k_world (mitsuba.Vector3f) – Directions of propagation of the incident paths

• tx_indices (drjit.cuda.ad.UInt) – Indices of the transmitters from which the rays originate

• active (drjit.cuda.ad.Bool) – Flags indicating if the paths should be added to the radio map

• diffracted_paths (bool) – Flags indicating if the paths are diffracted

• solid_angle (typing.Optional[drjit.cuda.ad.Float]) – Ray tubes solid angles [sr] for non-diffracted paths.Not required for diffracted paths.

• tx_positions (typing.Optional[mitsuba.Point3f]) – Positions of the transmitters

• wedges (typing.Optional[sionna.rt.utils.wedges.WedgeGeometry]) – Properties of the intersected wedges.Not required for non-diffracted paths.

• diff_point (typing.Optional[mitsuba.Point3f]) – Position of the diffraction point on the wedge.Not required for non-diffracted paths.

• wedges_samples_cnt (typing.Optional[drjit.cuda.ad.UInt]) – Number of samples on the wedge.Not required for non-diffracted paths.

propertycell_centers

Positions of the centers of the cells in the global coordinatesystem

Type:

mi.TensorXf[cells_per_dim_y,cells_per_dim_x,3]

propertycell_size

Size of a cell of the radio map [m]

Type:

mi.Point2f

propertycells_count

Total number of cells

Type:

int

propertycells_per_dim

Number of cells per dimension

Type:

mi.Point2u

propertycenter

Center of the radio map in the global coordinate system

Type:

mi.Point3f

propertymeasurement_surface

Mitsuba rectangle corresponding to theradio map measurement surface

Type:

mi.Rectangle

propertyorientation

Orientation of the radio map\((\alpha, \beta, \gamma)\)specified through three angles corresponding to a 3D rotation as definedin(3). An orientation of\((0,0,0)\) corresponds to aradio map that is parallel to the XY plane.

Type:

mi.Point3f

propertypath_gain

Path gains across the radio map from all transmitters [unitless, linear scale]

Type:

mi.TensorXf[num_tx,cells_per_dim_y,cells_per_dim_x]

propertyrx_cell_indices

Computes and returns the cell index positions corresponding toreceivers 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 sampledaround each transmitter, such that the selected metric, e.g., SINR, islarger thanmin_val_db and/or smaller thanmax_val_db.Similarly,min_dist andmax_dist define the minimum and maximumdistance of the random positions to the transmitter under consideration.By activating the flagtx_association, only positions are sampledfor which the selected metric is the highest across all transmitters.This is useful if one wants to ensure, e.g., that the sampled positionsfor each transmitter provide the highest SINR or RSS.

Note that due to the quantization of the radio map into cells it isnot guaranteed that all above parameters are exactly fulfilled for areturned position. This stems from the fact that everyindividual cell of the radio map describes the expectedaveragebehavior of the surface within this cell. For instance, it may happenthat half of the selected cell is shadowed and, thus, no path to thetransmitter exists but the average path gain is still larger than thegiven threshold. Please enable the flagcenter_pos to sample onlypositions from the cell centers.

importnumpyasnpimportsionnafromsionna.rtimportload_scene,PlanarArray,Transmitter,\RadioMapSolver,Receiverscene=load_scene(sionna.rt.scene.munich)# Configure antenna array for all transmittersscene.tx_array=PlanarArray(num_rows=1,num_cols=1,vertical_spacing=0.7,horizontal_spacing=0.5,pattern="iso",polarization="V")# Add a transmitterstx=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)fori,pinenumerate(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 and80m from the transmitter and a minimum path gain of -100 dB.Keep in mind that the transmitter can have a different height than theradio map which also contributes to this distance.For example if the transmitter is located 20m above the surface of theradio map and amin_dist of 20m is selected, also positionsdirectly below the transmitter are sampled.

Parameters:

• num_pos (int) – Number of returned random positions for each transmitter

• metric ("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 pathgain and SINR; [dBm] for RSS).Positions are only sampled from cells where the selected metric islarger than or equal to this value. Ignored ifNone.

• max_val_db (typing.Optional[float]) – Maximum value for the selected metric ([dB] for pathgain and SINR; [dBm] for RSS).Positions are only sampled from cells where the selected metric issmaller than or equal to this value.Ignored ifNone.

• min_dist (typing.Optional[float]) – Minimum distance [m] from transmitter for all randompositions. Ignored ifNone.

• max_dist (typing.Optional[float]) – Maximum distance [m] from transmitter for all randompositions. Ignored ifNone.

• tx_association (bool) – IfTrue, only positions associated with atransmitter are chosen, i.e., positions where the chosen metric isthe highest among all all transmitters. Else, a user located in asampled position for a specific transmitter may perceive a highermetric from another TX.

• center_pos (bool) – IfTrue, all returned positions are sampled fromthe cell center (i.e., the grid of the radio map). Otherwise, thepositions 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\((x,y,z)\) [m](shape:[num_tx,num_pos,3]) that are in cellsfulfilling 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 radiomap. IfNone, the maximum value over all transmitters for eachcell is shown.

• vmin (typing.Optional[float]) – Defines the minimum value [dB] for the colormap covers.If set toNone, then the minimum value across all cells is used.

• vmax (typing.Optional[float]) – Defines the maximum value [dB] for the colormap covers.If set toNone, then the maximum value across all cells is used.

• show_tx (bool) – If set toTrue, then the position of the transmittersare shown.

• show_rx (bool) – If set toTrue, then the position of the receivers areshown.

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 indicatedby “+” and “x” markers, respectively.

Parameters:

• metric ("path_gain" |"rss" |"sinr") – Metric to show

• show_tx (bool) – If set toTrue, then the position of the transmittersare shown.

• show_rx (bool) – If set toTrue, then the position of the receivers areshown.

• color_map (typing.Union[str,numpy.ndarray,None]) – Either the name of a Matplotlib colormap or a NumPyarray of shape (num_tx, 3) containing the RGB values for the colorsof the transmitters. If None, a default color map with the rightnumber of colors is generated.

Return type:

matplotlib.figure.Figure

Returns:

Figure showing the cell-to-transmitter association

propertysize

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 highestmetric, such as path gain, received signal strength (RSS), orSINR.

Parameters:

metric ("path_gain" |"rss" |"sinr") – Metric to be used

Return type:

drjit.cuda.ad.TensorXi

Returns:

Cell-to-transmitter association

propertytx_cell_indices

Cell index position of each transmitter in the format(column, row)

Type:

mi.Point2u

classsionna.rt.MeshRadioMap(scene,meas_surface)[source]

Mesh Radio Map

A mesh-based radio map is computed byaradio map solver for a measurement surfacedefined by a mesh. Each triangle of the mesh serves as a bin of the radiomap.

Parameters:

• scene (sionna.rt.scene.Scene) – Scene for which the radio map is computed

• meas_surface (mitsuba.Mesh) – Mesh to be used as the measurement surface

add_paths(e_fields,array_w,si,k_world,tx_indices,active,diffracted_paths,solid_angle=None,tx_positions=None,wedges=None,diff_point=None,wedges_samples_cnt=None)[source]

Adds the contribution of the paths that hit the measurement surfaceto the radio maps

The radio maps are updated in place.

Parameters:

• e_fields (mitsuba.Vector4f) – Electric fields as real-valued vectors of dimension 4

• array_w (typing.List[drjit.cuda.ad.Float]) – Weighting used to model the effect of the transmitterarray

• si (mitsuba.SurfaceInteraction3f) – Informations about the interaction with the measurementsurface

• k_world (mitsuba.Vector3f) – Directions of propagation of the incident paths

• tx_indices (drjit.cuda.ad.UInt) – Indices of the transmitters from which the rays originate

• active (drjit.cuda.ad.Bool) – Flags indicating if the paths should be added to the radio map

• diffracted_paths (bool) – Flags indicating if the paths are diffracted

• solid_angle (typing.Optional[drjit.cuda.ad.Float]) – Ray tubes solid angles [sr] for non-diffracted paths.Not required for diffracted paths.

• tx_positions (typing.Optional[mitsuba.Point3f]) – Positions of the transmitters

• wedges (typing.Optional[sionna.rt.utils.wedges.WedgeGeometry]) – Properties of the intersected wedges.Not required for non-diffracted paths.

• diff_point (typing.Optional[mitsuba.Point3f]) – Position of the diffraction point on the wedge.Not required for non-diffracted paths.

• wedges_samples_cnt (typing.Optional[drjit.cuda.ad.UInt]) – Number of samples on the wedge.Not required for non-diffracted paths.

propertycell_centers

Positions of the centers of the cells in the global coordinatesystem

Type:

mi.Point3f[cells_count,3]

propertycells_count

Total number of cells in the radio map

Type:

int

propertymeasurement_surface

Mitsuba shape corresponding to theradio map measurement surface

Type:

mi.Mesh

propertypath_gain

Path gains across the radio map from all transmitters [unitless, linear scale]

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 sampledaround each transmitter, such that the selected metric, e.g., SINR, islarger thanmin_val_db and/or smaller thanmax_val_db.Similarly,min_dist andmax_dist define the minimum and maximumdistance of the random positions to the transmitter under consideration.By activating the flagtx_association, only positions are sampledfor which the selected metric is the highest across all transmitters.This is useful if one wants to ensure, e.g., that the sampled positionsfor each transmitter provide the highest SINR or RSS.

Note that due to the quantization of the radio map into cells it isnot guaranteed that all above parameters are exactly fulfilled for areturned position. This stems from the fact that everyindividual cell of the radio map describes the expectedaveragebehavior of the surface within this cell. For instance, it may happenthat half of the selected cell is shadowed and, thus, no path to thetransmitter exists but the average path gain is still larger than thegiven threshold. Please enable the flagcenter_pos to sample onlypositions from the cell centers.

importnumpyasnpimportsionnafromsionna.rtimportload_scene,PlanarArray,Transmitter, \RadioMapSolver,Receiver,transform_meshscene=load_scene(sionna.rt.scene.san_francisco)# Configure antenna array for all transmittersscene.tx_array=PlanarArray(num_rows=1,num_cols=1,vertical_spacing=0.7,horizontal_spacing=0.5,pattern="iso",polarization="V")# Add a transmitterstx=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 metersmeasurement_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)fori,pinenumerate(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 and80m from the transmitter and a minimum path gain of -100 dB.Keep in mind that the transmitter can have a different height than theradio map which also contributes to this distance.For example if the transmitter is located 20m above the surface of theradio map and amin_dist of 20m is selected, also positionsdirectly below the transmitter are sampled.

Parameters:

• num_pos (int) – Number of returned random positions for each transmitter

• metric ("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 pathgain and SINR; [dBm] for RSS).Positions are only sampled from cells where the selected metric islarger than or equal to this value. Ignored ifNone.

• max_val_db (typing.Optional[float]) – Maximum value for the selected metric ([dB] for pathgain and SINR; [dBm] for RSS).Positions are only sampled from cells where the selected metric issmaller than or equal to this value.Ignored ifNone.

• min_dist (typing.Optional[float]) – Minimum distance [m] from transmitter for all randompositions. Ignored ifNone.

• max_dist (typing.Optional[float]) – Maximum distance [m] from transmitter for all randompositions. Ignored ifNone.

• tx_association (bool) – IfTrue, only positions associated with atransmitter are chosen, i.e., positions where the chosen metric isthe highest among all all transmitters. Else, a user located in asampled position for a specific transmitter may perceive a highermetric from another TX.

• center_pos (bool) – IfTrue, all returned positions are sampled fromthe cell center (i.e., the grid of the radio map). Otherwise, thepositions 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\((x,y,z)\) [m](shape:[num_tx,num_pos,3]) that are in cellsfulfilling the configured constraints

Returns:

Cell indices (shape[num_tx,num_pos])corresponding to the random positions

classsionna.rt.RadioMap(scene)[source]

Abstract base class for radio maps

A radio map is generated for the loaded scene for all transmitters usingaradio 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

abstractadd_paths(e_fields,array_w,si,k_world,tx_indices,active,diffracted_paths,solid_angle=None,tx_positions=None,wedges=None,diff_point=None,wedges_samples_cnt=None)[source]

Adds the contribution of the paths that hit the measurement surfaceto the radio maps

The radio maps are updated in place.

Parameters:

• e_fields (mitsuba.Vector4f) – Electric fields as real-valued vectors of dimension 4

• array_w (typing.List[drjit.cuda.ad.Float]) – Weighting used to model the effect of the transmitterarray

• si (mitsuba.SurfaceInteraction3f) – Informations about the interaction with the measurementsurface

• k_world (mitsuba.Vector3f) – Directions of propagation of the incident paths

• tx_indices (drjit.cuda.ad.UInt) – Indices of the transmitters from which the rays originate

• active (drjit.cuda.ad.Bool) – Flags indicating if the paths should be added to the radio map

• diffracted_paths (bool) – Flags indicating if the paths are diffracted

• solid_angle (typing.Optional[drjit.cuda.ad.Float]) – Ray tubes solid angles [sr] for non-diffracted paths.Not required for diffracted paths.

• tx_positions (typing.Optional[mitsuba.Point3f]) – Positions of the transmitters

• wedges (typing.Optional[sionna.rt.utils.wedges.WedgeGeometry]) – Properties of the intersected wedges.Not required for non-diffracted paths.

• diff_point (typing.Optional[mitsuba.Point3f]) – Position of the diffraction point on the wedge.Not required for non-diffracted paths.

• wedges_samples_cnt (typing.Optional[drjit.cuda.ad.UInt]) – Number of samples on the wedge.Not required for non-diffracted paths.

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 radiomap. IfNone, the maximum value over all transmitters for eachcell 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

abstractpropertycell_centers

Positions of the centers of the cells in the global coordinatesystem.

The type of this property depends on the subclass.

abstractpropertycells_count

Total number of cells in the radio map

Type:

int

abstractpropertymeasurement_surface

Mitsuba shape corresponding to theradio map measurement surface

Type:

mi.Shape

propertynum_rx

Number of receivers

Type:

int

propertynum_tx

Number of transmitters

Type:

int

abstractpropertypath_gain

Path gains across the radio map from all transmitters [unitless, linear scale]

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.

propertyrss

Received signal strength (RSS) across the radio map from alltransmitters [W]

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 sampledsuch that the selected metric, e.g., SINR, islarger thanmin_val_db and/or smaller thanmax_val_db.Similarly,min_dist andmax_dist define the minimum and maximumdistance of the random cells centers to the transmitter underconsideration.By activating the flagtx_association, only cells for which theselected metric is the highest across all transmitters are sampled.This is useful if one wants to ensure, e.g., that the sampled cellsfor each transmitter provide the highest SINR or RSS.

Parameters:

• num_cells (int) – Number of returned random cells for each transmitter

• metric ("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 pathgain and SINR; [dBm] for RSS).Only cells for which the selected metric is larger than or equal tothis value are sampled. Ignored ifNone.

• max_val_db (typing.Optional[float]) – Maximum value for the selected metric ([dB] for pathgain and SINR; [dBm] for RSS).Only cells for which the selected metric is smaller than or equal tothis value are sampled. Ignored ifNone.

• min_dist (typing.Optional[float]) – Minimum distance [m] from transmitter for all randomcells. Ignored ifNone.

• max_dist (typing.Optional[float]) – Maximum distance [m] from transmitter for all randomcells. Ignored ifNone.

• tx_association (bool) – IfTrue, only cells associated with atransmitter are chosen, i.e., cells where the chosen metric isthe highest among all all transmitters. Else, a user located in asampled cell for a specific transmitter may perceive a highermetric 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

propertysinr

SINR across the radio map from all transmitters [unitless, linear scale]

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 transmittertxand a specificmetric

Iftx isNone, then returns for each cell the maximum valueaccross 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 highestmetric, such as path gain, received signal strength (RSS), orSINR.

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 thatthere is no coverage for the cell.