SystemLevelScenario#

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

Bases: sionna.phy.object.Object

Base class for setting up the scenario for system level 3GPP channel simulation.

Scenarios for system level channel simulation, such as UMi, UMa, RMa, or InH, are defined by implementing this base class.

Parameters:

carrier_frequency (float) – Carrier frequency [Hz]
o2i_model (str) – Outdoor to indoor (O2I) pathloss model, used for indoor UTs. Must be "low" or "high". See Section 7.4.3 of TR 38.901. For UMi and UMa below 6 GHz, both choices use the backward-compatible model from Table 7.4.3-3 and therefore produce the same penetration loss.
ut_array (sionna.phy.channel.tr38901.antenna.PanelArray | sionna.phy.channel.tr38901.antenna.HandheldUTArray) – Antenna array configuration 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 configuration used by base stations. This can be a PanelArray or HandheldUTArray.
direction (str) – Link direction. Must be "uplink" or "downlink".
enable_pathloss (bool) – If True, apply pathloss. Otherwise doesn’t. Defaults to True.
enable_shadow_fading (bool) – If True, apply shadow fading. Otherwise doesn’t. Defaults to True.
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".

Methods

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

Pre-allocate all tensors used for topology updates.

This method must be called before using set_topology for the first time inside a torch.compile-decorated function. Outside a compiled function, it is optional because the first eager call registers the buffers automatically.

Calling this method again reinitializes all topology buffers to the new shapes (equivalent to reset_topology() + allocate).

After the first set_topology call (or after calling this method), the shapes of topology tensors are frozen and cannot be changed. This is required for torch.compile with mode=”reduce-overhead”.

Parameters:

batch_size (int) – Batch size
num_bs (int) – Number of base stations
num_ut (int) – Number of user terminals

Attributes

property basic_pathloss: torch.Tensor#: Basic pathloss component [dB]. See section 7.4.1 of 38.901 specification. Shape [batch size, num BS, num UT]

property batch_size: int#: Batch size

broadcast_params(parameter_value_los, parameter_value_nlos, parameter_value_o2i) → torch.Tensor[source]#: Broadcast parameters to the shape [batch size, number of base stations, number of UTs] based on the link state (LoS, NLoS, indoor).

property bs_array: sionna.phy.channel.tr38901.antenna.PanelArray | sionna.phy.channel.tr38901.antenna.HandheldUTArray#: Antenna array used by base stations.

property bs_loc: torch.Tensor#: Locations of base stations [m]. Shape [batch size, number of base stations, 3]

property bs_orientations: torch.Tensor#: Orientations of base stations [radian]. Shape [batch size, number of base stations, 3]

property bs_site_ids: torch.Tensor#: Site identifier of each BS. Shape [batch size, number of base stations]

property bs_site_representatives: torch.Tensor#: Representative BS index for each BS site. Shape [batch size, number of base stations]

property bs_virtual_loc: torch.Tensor#: Virtual location of base stations, relative to each UT position [m]. Useful in case of wraparound. Broadcastable to [batch size, number of UTs, number of base stations, 3]

property carrier_frequency: torch.Tensor#: Carrier frequency [Hz]

abstractmethod 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 – Clipped carrier frequency, that should be used for LSP computation

property direction: str#: Direction of communication. Either "uplink" or "downlink".

property distance_2d: torch.Tensor#: Distance between each UT and each BS in the X-Y plane [m]. Shape [batch size, number of base stations, number of UTs]

property distance_2d_in: torch.Tensor#: Indoor distance between each UT and BS in the X-Y plane [m], i.e., part of the total distance that corresponds to indoor propagation in the X-Y plane. Set to 0 for UTs located outdoor. Shape [batch size, number of base stations, number of UTs]

property distance_2d_out: torch.Tensor#: Outdoor distance between each UT and BS in the X-Y plane [m], i.e., part of the total distance that corresponds to outdoor propagation in the X-Y plane. Equals distance_2d for UTs located outdoor. Shape [batch size, number of base stations, number of UTs]

property distance_3d: torch.Tensor#: Distance between each UT and each BS [m]. Shape [batch size, number of base stations, number of UTs]

property distance_3d_in: torch.Tensor#: Indoor distance between each UT and BS [m], i.e., part of the total distance that corresponds to indoor propagation. Set to 0 for UTs located outdoor. Shape [batch size, number of base stations, number of UTs]

property distance_3d_out: torch.Tensor#: Outdoor distance between each UT and BS [m], i.e., part of the total distance that corresponds to outdoor propagation. Equals distance_3d for UTs located outdoor. Shape [batch size, number of base stations, number of UTs]

get_param(parameter_name: str) → torch.Tensor[source]#

Given a parameter_name used in the configuration file, returns a tensor with shape [batch size, number of base stations, number of UTs] of the parameter value according to each BS-UT link state (LoS, NLoS, indoor).

Parameters:: parameter_name (str) – Name of the parameter used in the configuration file
Outputs:: value – Parameter value for each BS-UT link, shape [batch size, number of base stations, number of UTs]

property h_bs: torch.Tensor#: Height of base stations [m]. Shape [batch size, number of base stations]

property h_ut: torch.Tensor#: Height of UTs [m]. Shape [batch size, number of UTs]

property indoor: torch.Tensor#: Indoor state of UTs. True is indoor, False otherwise. Shape [batch size, number of UTs]

property indoor_links_can_be_los: bool#: Allow indoor links to keep their sampled outdoor LoS condition.

property indoor_links_use_o2i_zenith_model: bool#: Use O2I zenith-angle generation rules for indoor UTs.

property lambda_0: torch.Tensor#: Wavelength [m]

property los: torch.Tensor#: LoS state of BS-UT links. True if LoS, False otherwise. Shape [batch size, number of base stations, number of UTs]

property los_aoa: torch.Tensor#: LoS azimuth angle of arrival of each BS-UT link [deg]. Shape [batch size, number of base stations, number of UTs]

property los_aod: torch.Tensor#: LoS azimuth angle of departure of each BS-UT link [deg]. Shape [batch size, number of base stations, number of UTs]

abstract property los_parameter_filepath: str#: Path of the configuration file for LoS scenario

abstract property los_probability: torch.Tensor#: Probability of each UT to be LoS. Used to randomly generate LoS status of outdoor UTs. Shape [batch size, number of UTs]

property los_zoa: torch.Tensor#: LoS zenith angle of arrival of each BS-UT link [deg]. Shape [batch size, number of base stations, number of UTs]

property los_zod: torch.Tensor#: LoS zenith angle of departure of each BS-UT link [deg]. Shape [batch size, number of base stations, number of UTs]

property lsp_log_mean: torch.Tensor#: Mean of LSPs in the log domain. Shape [batch size, number of base stations, number of UTs, 7]. The last dimension corresponds to the LSPs, in the following order: DS - ASD - ASA - SF - K - ZSA - ZSD

property lsp_log_std: torch.Tensor#: STD of LSPs in the log domain. Shape [batch size, number of base stations, number of UTs, 7]. The last dimension corresponds to the LSPs, in the following order: DS - ASD - ASA - SF - K - ZSA - ZSD

property matrix_ut_distance_2d: torch.Tensor#: Distance between all pairs of UTs in the X-Y plane [m]. Shape [batch size, number of UTs, number of UTs]

abstract property max_2d_in: torch.Tensor#: Maximum indoor 2D distance for indoor UTs [m]

abstract property min_2d_in: torch.Tensor#: Minimum indoor 2D distance for indoor UTs [m]

abstract property nlos_parameter_filepath: str#: Path of the configuration file for NLoS scenario

property num_bs: int#: Number of base stations

property num_clusters_indoor: int#: Number of clusters for indoor scenario

property num_clusters_los: int#: Number of clusters for LoS scenario

property num_clusters_max: int#: Maximum number of clusters over indoor, LoS, and NLoS scenarios

property num_clusters_nlos: int#: Number of clusters for NLoS scenario

property num_ut: int#: Number of UTs

property o2i_model: str#: O2I model used for pathloss computation of indoor UTs. Either "low" or "high". See section 7.4.3 of TR 38.901.

abstract property o2i_parameter_filepath: str#: Path of the configuration file for indoor scenario

property o2i_pathloss_enabled: bool#: Apply outdoor-to-indoor penetration loss to indoor UTs.

property outdoor_los: torch.Tensor#

LoS condition of the outdoor part of each BS-UT link.

For outdoor UTs, this is identical to los. For O2I links, it retains the sampled outdoor propagation condition while los is False, because an O2I link has no deterministic LoS component. Shape [batch size, number of base stations, number of UTs].

property pathloss_enabled: bool#: True if pathloss is enabled. False otherwise.

abstract property rays_per_cluster: int#: Number of rays per cluster

reset_topology() → None[source]#

Reset the topology to allow different batch_size/num_ut/num_bs.

This method clears all topology buffers and returns the scenario to its initial state. The next set_topology call will re-initialize the buffers with the new shapes and freeze again.

Use this when you need to change the batch_size, num_ut, or num_bs, for example when switching between training and evaluation with different batch sizes.

Note: After reset, the next set_topology call will re-freeze. If using torch.compile, this will trigger recompilation.

property scenario_kind: str#: Scenario family identifier such as "umi", "uma", or "rma".

set_spatial_consistency_enabled(enabled: bool) → None[source]#

Enable or disable additional static spatial random fields.

Parameters:: enabled (bool)

Set the network topology.

It is possible to set up a different network topology for each batch example.

When calling this function, not specifying a parameter leads to the reuse of the previously given value. Not specifying a value that was not set at a former call raises an error.

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 base stations [m]. Shape [batch size, number of base stations, 3]
ut_orientations (torch.Tensor | None) – Orientations of the UTs arrays [radian]. Shape [batch size, number of UTs, 3]
bs_orientations (torch.Tensor | None) – Orientations of the base-station arrays [radian]. Shape [batch size, number of base stations, 3]
ut_velocities (torch.Tensor | None) – Velocity vectors of UTs [m/s]. Shape [batch size, number of UTs, 3]
in_state (torch.Tensor | None) – Indoor/outdoor state of UTs. True means indoor and False means outdoor. Shape [batch size, number of UTs]
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, number of base stations, number of UTs] or [number of base stations, number of UTs]. 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 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. If neither bs_virtual_loc nor bs_loc are specified, then the previous value is 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 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 [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. 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 [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 or link. Below 6 GHz, UMi and UMa use the legacy link-specific model and accept shape [batch size, number of base stations, number of UTs]. Other O2I models use a UT-specific value with shape [batch size, number of UTs]. Values for outdoor UTs are ignored.
ut_spatial_region_ids (torch.Tensor | None) – Optional correlation-region identifier for every UT. Unequal IDs decorrelate LSP fields and the additional fields controlled by spatial consistency; correlation within a region uses 2D distance. IDs do not add floor penetration loss or change pathloss or geometry; blockage model A uses the same partition when enabled. If omitted on the first call, indoor UTs in outdoor scenarios are assigned from a 3 m floor grid, while all InH/InF UTs use one region. The fallback does not identify separate buildings. Shape [number of UTs] or [batch size, number of UTs].

Outputs:

updated – True if the topology was updated, False otherwise

property shadow_fading_enabled: bool#: True if shadow fading is enabled. False otherwise.

share_by_bs_site(value: torch.Tensor) → torch.Tensor[source]#

Share BS-link values among co-sited base stations using representative links.

Parameters:: value (torch.Tensor)

property spatial_consistency_track_ids: torch.Tensor | None#

Optional grouping identifiers for positions on the same UT track.

When spatial consistency is enabled, UT entries with equal identifiers in one topology snapshot share the cluster-specific angle signs and random ray coupling. The identifiers do not preserve random variables across topology updates. None means that all UT entries are treated as distinct simultaneous UTs. Shape [batch size, number of UTs].

spatial_correlation_matrix(correlation_distance: float) → torch.Tensor[source]#

Computes and returns a 2D spatial exponential correlation matrix \(C\) over the UTs, such that \(C\) has shape (number of UTs) x (number of UTs), and

\[C_{n,m} = \exp\left(-\frac{d_{n,m}}{D}\right)\]

where \(d_{n,m}\) is the distance between UT \(n\) and UT \(m\) in the X-Y plane, and \(D\) the correlation distance.

Parameters:: correlation_distance (float) – Correlation distance, i.e., distance such that the correlation is \(e^{-1} \approx 0.37\)
Outputs:: C – Spatial correlation \(C\), shape [batch size, number of UTs, number of UTs]

property spec_version: str#: TR 38.901 parameter-table version.

property use_indoor_lsp_params: bool#: Use the scenario’s dedicated indoor/O2I LSP and ray parameters.

property ut_array: sionna.phy.channel.tr38901.antenna.PanelArray | sionna.phy.channel.tr38901.antenna.HandheldUTArray#: Antenna array used by UTs.

property ut_loc: torch.Tensor#: Locations of UTs [m]. Shape [batch size, number of UTs, 3]

property ut_orientations: torch.Tensor#: Orientations of UTs [radian]. Shape [batch size, number of UTs, 3]

property ut_spatial_region_ids: torch.Tensor#

Correlation-region identifier of each UT.

Unequal identifiers decorrelate supported spatial random fields. The labels do not alter pathloss or geometry; blockage model A uses the same partition when enabled. Identifiers should be unique across buildings. Shape [batch size, number of UTs].

property ut_velocities: torch.Tensor#: UT velocities [m/s]. Shape [batch size, number of UTs, 3]

property zod_offset: torch.Tensor#: Zenith angle of departure offset