UMa#

class sionna.phy.channel.tr38901.UMa(carrier_frequency: float, o2i_model: str, 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, 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)[source]#

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

Urban macrocell (UMa) channel model from 3GPP [TR38901V1920] specification.

Setting up a UMa 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. TR 38.901 calibration-style multi-cell drops can be generated with gen_tr38901_multicell_topology(); more general hexagonal grid drops 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]

  • o2i_model (str) – Outdoor-to-indoor loss model for UTs located indoor. Set this parameter to "low" to use the low-loss model, or to "high" to use the high-loss model. See section 7.4.3 of [TR38901V1920] for details.

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

  • 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, additionally generate LoS/NLoS states, applicable O2I terms, and small-scale random variables from spatially correlated fields for the current topology snapshot. LSP spatial correlation is always applied. Random fields are not retained across topology updates. 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, UMa
from sionna.sys import gen_tr38901_multicell_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 = UMa(carrier_frequency=carrier_frequency,
                    o2i_model='low',
                    ut_array=ut_array,
                    bs_array=bs_array,
                    direction='downlink',
                    device=device)

topology = gen_tr38901_multicell_topology("uma",
                                          batch_size=1,
                                          num_ut_per_sector=1,
                                          carrier_frequency=carrier_frequency,
                                          num_rings=1,
                                          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) → None[source]#

Set the network topology.

This method forwards to set_topology(). UMa calibration-style multi-cell topologies can be generated with gen_tr38901_multicell_topology(); more general 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 grouping identifiers for UT entries representing positions on one track in the current topology snapshot. When spatial consistency is enabled, equal IDs share cluster-angle signs and random ray-coupling permutations, but do not retain random variables across topology updates. 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] for the current O2I model, or [batch size, num_bs, num_ut] below 6 GHz.

  • ut_spatial_region_ids (torch.Tensor | None) – Optional integer correlation-region identifier for every UT. Unequal IDs decorrelate supported random fields; correlation within a region uses 2D distance. IDs do not add floor loss or change pathloss or geometry. Blockage model A uses the same partition when enabled. Shape [num_ut] or [batch size, num_ut].