SystemLevelChannel#

class sionna.phy.channel.tr38901.SystemLevelChannel(scenario: sionna.phy.channel.tr38901.system_level_scenario.SystemLevelScenario, always_generate_lsp: bool = False, precision: str | None = None, device: str | None = None, 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: torch.Tensor | None = None, blockage_screen_widths: torch.Tensor | None = None, blockage_screen_heights: torch.Tensor | None = None)[source]#

Bases: sionna.phy.channel.channel_model.ChannelModel

Base class for implementing 3GPP system level channel models, such as UMi, UMa, RMa, InH, and InF.

Parameters:

scenario (sionna.phy.channel.tr38901.system_level_scenario.SystemLevelScenario) – Scenario for the channel simulation
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.
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 applied independently of this flag. Random fields are not retained across topology updates; the stateful mobility procedure of Section 7.6.3.2 is not implemented. See Spatial Consistency. Defaults to False.
enable_blockage (bool) – If True, apply the selected blockage model according to Section 7.6.4 of [TR38901V1920]. Blockage is disabled by default for backwards compatibility. The optional, on-demand temporal variability of blockage is currently not supported.
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 as specified by [TR38901V1920].
blockage_model (str) – Blockage model variant. Must be "A" or "B". Defaults to "A".
blockage_screen_centers (torch.Tensor | None) – Blockage model B screen centres [m]. Required if blockage_model is "B". Shape [num_blockers, 3] or [batch size, num_blockers, 3].
blockage_screen_widths (torch.Tensor | None) – Blockage model B screen widths [m]. Shape [num_blockers] or [batch size, num_blockers].
blockage_screen_heights (torch.Tensor | None) – Blockage model B screen heights [m]. Shape [num_blockers] or [batch size, num_blockers].

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].
rays – Rays. Sampled rays. Only returned if self.return_rays is True.

Examples

import torch
from sionna.phy.channel.tr38901 import SystemLevelScenario, SystemLevelChannel

# Assuming a concrete scenario implementation exists
scenario = MyScenario(carrier_frequency=3.5e9, ...)
channel = SystemLevelChannel(scenario)

# Set topology
channel.set_topology(ut_loc, bs_loc, ut_orientations, bs_orientations,
                     ut_velocities, in_state)

# Generate channel
h, delays = channel(num_time_samples=100, sampling_frequency=1e6)

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 should be called before using set_topology within a torch.compile-decorated function with CUDAGraphs enabled. It ensures that all internal tensors are pre-allocated with fixed shapes, allowing subsequent set_topology calls to use in-place operations that are compatible with CUDAGraph capture.

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

After calling this method, the shapes of the topology cannot change.

Parameters:

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

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 channel to its initial state. The next set_topology call will re-initialize the buffers with the new shapes.

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: If using torch.compile, this will trigger recompilation.

Attributes

property return_rays: bool#: Indicates whether the call method returns the generated rays.

sample_lsp() → sionna.phy.channel.tr38901.lsp.LSP[source]#

Sample large-scale parameters for the current topology.

This method returns a fresh realization of the TR 38.901 large-scale parameters (LSPs) for the topology configured with set_topology(). It is useful for diagnostics and calibration plots, e.g., to inspect the spatial correlation of shadow fading, delay spread, or angular spreads. The returned sample is not cached by the channel.

Outputs:: lsp – LSP. Fresh LSP realization.

Set the network topology.

It is possible to set up a different network topology for each batch example. The batch size used when setting up the network topology is used for the link simulations.

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, 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 the same track in the current topology snapshot. When spatial consistency is enabled, equal IDs share cluster-angle signs and random ray-coupling permutations. They 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] for the legacy below-6-GHz UMi/UMa model.
ut_spatial_region_ids (torch.Tensor | None) – Optional integer correlation-region identifier for every UT. Unequal IDs decorrelate LSP fields and the additional fields controlled by enable_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 initially, UMi/UMa/RMa infer a 3 m floor grid for indoor UTs, while InH/InF use one common region. The inferred IDs do not distinguish buildings. Shape [num_ut] or [batch size, num_ut].
in_car (torch.Tensor | None) – RMa-only in-car state of every UT. If omitted for the first RMa topology, all non-indoor UTs are treated as in-car per Table 7.2-3. Shape [batch size, num_ut].

show_topology(bs_index: int = 0, batch_index: int = 0) → None[source]#

Show the network topology of the batch example with index batch_index.

The bs_index parameter specifies with respect to which BS the LoS/NLoS state of UTs is indicated.

Parameters:

bs_index (int) – BS index with respect to which the LoS/NLoS state of UTs is indicated. Defaults to 0.
batch_index (int) – Batch example for which the topology is shown. Defaults to 0.