RMa#

class sionna.phy.channel.tr38901.RMa(carrier_frequency: float, ut_array: sionna.phy.channel.tr38901.antenna.PanelArray | sionna.phy.channel.tr38901.antenna.HandheldUTArray, bs_array: sionna.phy.channel.tr38901.antenna.PanelArray | sionna.phy.channel.tr38901.antenna.HandheldUTArray, direction: str, enable_pathloss: bool = True, enable_shadow_fading: bool = True, average_street_width: float = 20.0, average_building_height: float = 5.0, always_generate_lsp: bool = False, precision: str | None = None, device: str | None = None, spec_version: str = '19.2', enable_spatial_consistency: bool = False, enable_blockage: bool = False, blockage_self_blocking: str | None = None, blockage_num_non_self_blockers: int = 4, blockage_model: str = 'A', blockage_screen_centers=None, blockage_screen_widths=None, blockage_screen_heights=None, car_window_type: str = 'ordinary')[source]#

Bases: sionna.phy.channel.tr38901.system_level_channel.SystemLevelChannel

Rural macrocell (RMa) channel model from 3GPP [TR38901V1920] specification.

Setting up an RMa model requires configuring the network topology, i.e., the UT and base-station locations, UT velocities, etc. This is achieved using the set_topology() method. Setting a different topology for each batch example is possible. The batch size used when setting up the network topology is used for the link simulations. Hexagonal-grid RMa topologies can be generated with gen_hexgrid_topology().

Spatial consistency and blockage are optional add-on features, both disabled by default. See Spatial Consistency and Blockage for details.

Parameters:

  • carrier_frequency (float) – Carrier frequency [Hz]

  • ut_array (sionna.phy.channel.tr38901.antenna.PanelArray | sionna.phy.channel.tr38901.antenna.HandheldUTArray) – Antenna array used by the UTs. This can be a PanelArray or HandheldUTArray.

  • bs_array (sionna.phy.channel.tr38901.antenna.PanelArray | sionna.phy.channel.tr38901.antenna.HandheldUTArray) – Antenna array used by the base stations. This can be a PanelArray or HandheldUTArray.

  • direction (str) – Link direction. Either "uplink" or "downlink".

  • enable_pathloss (bool) – If True, apply pathloss. Otherwise don’t. Defaults to True.

  • enable_shadow_fading (bool) – If True, apply shadow fading. Otherwise don’t. Defaults to True.

  • average_street_width (float) – Average street width [m]. Defaults to 20.0.

  • average_building_height (float) – Average building height [m]. Defaults to 5.0.

  • car_window_type (str) – Car-window type for Section 7.4.3.2. Must be "ordinary" (9 dB mean penetration loss) or "metallized" (20 dB mean). Defaults to "ordinary". The car penetration loss is sampled once per in-car UT and shared by all of its BS links.

  • always_generate_lsp (bool) – If True, new large scale parameters (LSPs) are generated for every new generation of channel impulse responses. Otherwise, always reuse the same LSPs, except if the topology is changed. Defaults to False.

  • precision (str | None) – Precision used for internal calculations and outputs. If set to None, precision is used.

  • device (str | None) – Device for computation (e.g., ‘cpu’, ‘cuda:0’). If None, device is used.

  • spec_version (str) – Version of the TR 38.901 parameter tables to use. Supported values are "16.1" and "19.2". Defaults to "19.2".

  • enable_spatial_consistency (bool) – If True, generate stochastic LoS/NLoS states and small-scale random variables from spatially consistent random fields according to Sections 7.6.3.1, 7.6.3.3, and 7.6.3.4 of [TR38901V1920]. See Spatial Consistency. Defaults to False.

  • enable_blockage (bool) – If True, apply the selected blockage model according to Section 7.6.4 of [TR38901V1920]. The optional, on-demand temporal variability of blockage is currently not supported. See Blockage. Defaults to False.

  • blockage_self_blocking (str | None) – Self-blocking mode for blockage model A. Must explicitly be "portrait" or "landscape" when model A is enabled. The explicit value "none" disables self-blocking as a non-standard extension. None is valid only when blockage is disabled or model B is selected.

  • blockage_num_non_self_blockers (int) – Number of non-self-blocking regions for blockage model A. Defaults to 4.

  • blockage_model (str) – Blockage model variant. Must be "A" or "B". Defaults to "A".

  • blockage_screen_centers – Blockage model B screen centres [m].

  • blockage_screen_widths – Blockage model B screen widths [m].

  • blockage_screen_heights – Blockage model B screen heights [m].

Inputs:

  • num_time_samples – int. Number of time samples.

  • sampling_frequency – float. Sampling frequency [Hz].

Outputs:

  • a – [batch size, num_rx, num_rx_ant, num_tx, num_tx_ant, num_paths, num_time_samples], torch.complex. Path coefficients.

  • tau – [batch size, num_rx, num_tx, num_paths], torch.float. Path delays [s].

Examples

import torch
from sionna.phy.channel.tr38901 import PanelArray, RMa
from sionna.sys import gen_hexgrid_topology

device = "cuda:0" if torch.cuda.is_available() else "cpu"
carrier_frequency = 3.5e9

bs_array = PanelArray(num_rows_per_panel=1, num_cols_per_panel=1,
                      polarization='dual', polarization_type='cross',
                      antenna_pattern='38.901',
                      carrier_frequency=carrier_frequency,
                      device=device)
ut_array = PanelArray(num_rows_per_panel=1, num_cols_per_panel=1,
                      polarization='single', polarization_type='V',
                      antenna_pattern='omni',
                      carrier_frequency=carrier_frequency,
                      device=device)

channel_model = RMa(carrier_frequency=carrier_frequency,
                    ut_array=ut_array,
                    bs_array=bs_array,
                    direction='downlink',
                    device=device)

topology = gen_hexgrid_topology(batch_size=1,
                                num_rings=1,
                                num_ut_per_sector=1,
                                scenario="rma",
                                device=device)

# The helper output can be replaced by explicit tensors for arbitrary
# geometries.
channel_model.set_topology(*topology)

h, tau = channel_model(num_time_samples=1, sampling_frequency=1e6)

Methods

set_topology(ut_loc: torch.Tensor | None = None, bs_loc: torch.Tensor | None = None, ut_orientations: torch.Tensor | None = None, bs_orientations: torch.Tensor | None = None, ut_velocities: torch.Tensor | None = None, in_state: torch.Tensor | None = None, los: bool | str | torch.Tensor | None = None, bs_virtual_loc: torch.Tensor | None = None, bs_site_ids: torch.Tensor | None = None, spatial_consistency_track_ids: torch.Tensor | None = None, distance_2d_in: torch.Tensor | None = None, ut_spatial_region_ids: torch.Tensor | None = None, in_car: torch.Tensor | None = None) → None[source]#

Set the network topology.

This method forwards to set_topology(). RMa hexagonal-grid topologies can be generated with gen_hexgrid_topology().

Parameters:

  • ut_loc (torch.Tensor | None) – Locations of the UTs [m]. Shape [batch size, num_ut, 3].

  • bs_loc (torch.Tensor | None) – Locations of the base stations [m]. Shape [batch size, num_bs, 3].

  • ut_orientations (torch.Tensor | None) – Orientations of the UT arrays [radian]. Shape [batch size, num_ut, 3].

  • bs_orientations (torch.Tensor | None) – Orientations of the BS arrays [radian]. Shape [batch size, num_bs, 3].

  • ut_velocities (torch.Tensor | None) – Velocity vectors of the UTs [m/s]. Shape [batch size, num_ut, 3].

  • in_state (torch.Tensor | None) – Indoor/outdoor state of the UTs. True means indoor and False means outdoor. Shape [batch size, num_ut].

  • los (bool | str | torch.Tensor | None) – LoS/NLoS state control. If set to True, all outdoor UTs are forced to be in LoS. If set to False, all outdoor UTs are forced to be in NLoS. If a boolean tensor is provided, it specifies the requested LoS/NLoS state for each BS-UT link with shape [batch size, num_bs, num_ut] or [num_bs, num_ut]. If set to "random", fresh stochastic LoS/NLoS states are sampled following Section 7.4.2 of [TR38901V1920]. If set to None, the previous setting is reused; on the first call this is equivalent to "random".

  • bs_virtual_loc (torch.Tensor | None) – Virtual locations of the base stations for each UT [m]. Used to compute BS-UT relative distance and angles. If None while bs_loc is specified, then it is set to bs_loc upon reshaping. Shape [batch size, num_bs, num_ut, 3].

  • bs_site_ids (torch.Tensor | None) – Site identifier of each BS. Co-sited base stations share the same site identifier and use common site-level random quantities, such as co-sited LSPs. If None, exact duplicate BS locations are treated as co-sited; near duplicates remain separate and emit a warning. Shape [num_bs] or [batch size, num_bs].

  • spatial_consistency_track_ids (torch.Tensor | None) – Optional UT track identifiers for spatial-consistency mobility. UT entries with equal identifiers in the same batch item are interpreted as different positions of the same moving UT for the cluster-specific angle signs and random ray coupling, which remain fixed per simulation drop according to TR 38.901 Section 7.6.3.1. Shape [num_ut] or [batch size, num_ut].

  • distance_2d_in (torch.Tensor | None) – Optional pre-sampled indoor 2D distance [m] for every UT. Values for outdoor UTs are ignored. Shape [batch size, num_ut].

  • ut_spatial_region_ids (torch.Tensor | None) – Optional integer floor or spatial-region identifier for every UT. Different IDs decorrelate spatial random fields. Shape [num_ut] or [batch size, num_ut].

  • in_car (torch.Tensor | None) – In-car state of every UT. Indoor and in-car states are mutually exclusive. If omitted initially, all non-indoor UTs are treated as in-car, matching Table 7.2-3. Set this explicitly to False for unprotected outdoor UTs. Shape [batch size, num_ut].