RMaScenario#

class sionna.phy.channel.tr38901.RMaScenario(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, precision: str | None = None, device: str | None = None, spec_version: str = '19.2', car_window_type: str = 'ordinary')[source]#

Bases: sionna.phy.channel.tr38901.system_level_scenario.SystemLevelScenario

3GPP TR 38.901 rural macrocell (RMa) channel model scenario.

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 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 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.

  • 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".

  • car_window_type (str) – Car-window type for the car penetration model of Section 7.4.3.2. Must be "ordinary" (9 dB mean) 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.

Examples

>>> from sionna.phy.channel.tr38901 import PanelArray, RMaScenario
>>> # Configure antenna arrays
>>> ut_array = PanelArray(num_rows_per_panel=1,
...                       num_cols_per_panel=1,
...                       polarization="single",
...                       polarization_type="V",
...                       antenna_pattern="omni",
...                       carrier_frequency=3.5e9)
>>> bs_array = PanelArray(num_rows_per_panel=4,
...                       num_cols_per_panel=4,
...                       polarization="dual",
...                       polarization_type="cross",
...                       antenna_pattern="38.901",
...                       carrier_frequency=3.5e9)
>>> scenario = RMaScenario(carrier_frequency=3.5e9,
...                        ut_array=ut_array,
...                        bs_array=bs_array,
...                        direction="downlink")

Methods

allocate_topology_tensors(batch_size: int, num_bs: int, num_ut: int) → None[source]#

Pre-allocate topology-dependent RMa tensors.

This is required before the first topology update inside a torch.compile()-decorated function. Calling it again resets the current topology and allocates tensors with the requested shapes.

Parameters:

  • batch_size (int) – Batch size.

  • num_bs (int) – Number of base stations.

  • num_ut (int) – Number of user terminals.

Attributes

property average_building_height: torch.Tensor#

Average building height [m]

property average_street_width: torch.Tensor#

Average street width [m]

property car_penetration_loss_mean: torch.Tensor#

Mean car penetration loss [dB].

property car_window_type: str#

Car-window type used by the car penetration model.

clip_carrier_frequency_lsp(fc: torch.Tensor) → torch.Tensor[source]#

Clip the carrier frequency fc in GHz for LSP calculation.

Parameters:

fc (torch.Tensor) – Carrier frequency [GHz]

Outputs:

fc_clipped – float. Clipped carrier frequency, that should be used for LSP computation.

property in_car: torch.Tensor#

In-car state of UTs. Shape [batch size, number of UTs].

property los_parameter_filepath: str#

Path of the configuration file for LoS scenario

property los_probability: torch.Tensor#

Probability of each UT to be LoS. Used to randomly generate LoS status of outdoor UTs.

Computed following section 7.4.2 of TR 38.901.

Shape [batch size, num_bs, num_ut]

property max_2d_in: torch.Tensor#

Maximum indoor 2D distance for indoor UTs [m]

property min_2d_in: torch.Tensor#

Minimum indoor 2D distance for indoor UTs [m]

property nlos_parameter_filepath: str#

Path of the configuration file for NLoS scenario

property o2i_parameter_filepath: str#

Path of the configuration file for indoor scenario

property rays_per_cluster: int#

Number of rays per cluster

reset_topology() → None[source]#

Reset topology-dependent RMa state.

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) → bool[source]#

Set the RMa topology and optional UT-specific in-car state.

Unspecified parameters reuse their value from the previous call. Parameters that have never been set must be provided on the first call.

If in_car is omitted on the first call, every non-indoor UT is treated as in-car, matching the default population in Table 7.2-3 of [TR38901V1920]. This inferred mask follows later in_state updates. Once in_car is supplied explicitly, omission on later calls reuses that explicit mask. Set in_car=False for pedestrian or otherwise unprotected outdoor UTs.

Parameters:

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

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

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

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

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

  • in_state (torch.Tensor | None) – Indoor state of every UT. True means indoor and False means non-indoor. Shape [batch size, number of UTs].

  • los (bool | str | torch.Tensor | None) – LoS/NLoS state control. A scalar boolean forces that state for every outdoor link. A boolean tensor specifies each link with shape [batch size, number of base stations, number of UTs] or [number of base stations, number of UTs]. "random" draws fresh states following Section 7.4.2; None reuses the previous setting and is equivalent to "random" on the first call.

  • bs_virtual_loc (torch.Tensor | None) – Virtual BS locations for each UT [m], used for wraparound distances and angles. If omitted while bs_loc is supplied, the physical BS locations are used. Shape [batch size, number of base stations, number of UTs, 3].

  • bs_site_ids (torch.Tensor | None) – Site identifier of each BS. Co-sited base stations share site-level random quantities. If omitted, exact duplicate BS locations are treated as co-sited. Shape [number of base stations] or [batch size, number of base stations].

  • spatial_consistency_track_ids (torch.Tensor | None) – Optional grouping identifiers for UT entries representing positions on the same track in the current topology snapshot. Equal identifiers share cluster-specific angle signs and random ray-coupling permutations. Shape [number of UTs] or [batch size, number of UTs].

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

  • ut_spatial_region_ids (torch.Tensor | None) – Optional correlation-region identifier for every UT. Unequal identifiers decorrelate supported spatial random fields without changing pathloss or geometry. Shape [number of UTs] or [batch size, number of UTs].

  • in_car (torch.Tensor | None) – In-car state of every UT. In-car and indoor states are mutually exclusive. Shape [batch size, number of UTs].

Outputs:

updated – True if the topology was updated, False otherwise.