InF#

class sionna.phy.channel.tr38901.InF(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, factory_scenario: str = 'SH', hall_dimensions: tuple[float, float, float] | None = None, clutter_density: float | None = None, clutter_size: float | None = None, clutter_height: float | None = None, enable_pathloss: bool = True, enable_shadow_fading: bool = True, always_generate_lsp: bool = False, precision: str | None = None, device: str | None = None, enable_spatial_consistency: bool = False, enable_blockage: bool = False, blockage_screen_centers=None, blockage_screen_widths=None, blockage_screen_heights=None, spec_version: str = '19.2')[source]#

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

Indoor factory (InF) channel model. It implements the indoor-factory scenario from Section 7 of 3GPP TR 38.901 [TR38901V1920]. The factory_scenario parameter selects one of the InF-SL (sparse clutter, low BS height), InF-DL (dense clutter, low BS height), InF-SH (sparse clutter, high BS height), InF-DH (dense clutter, high BS height), or InF-HH (high transmitter and high receiver) sub-scenarios.

For InF-SL, InF-DL, InF-SH, and InF-DH, omitted hall and clutter values use the calibration assumptions from Table 7.8-7 of [TR38901V1920]. InF-HH is not included in that table. Its defaults (300, 150, 10) m, 0.0, 1.0 m, and 0.0 m for hall dimensions, clutter density, clutter size, and clutter height are implementation assumptions, not standardized calibration values. Pass explicit values for a particular InF-HH layout.

Internally, this channel constructs an InFScenario, which stores the factory layout, versioned channel parameters, and topology-dependent state. Most users should instantiate InF; the scenario class is exposed for lower-level use with components such as LSPGenerator.

Setting up an InF 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. If in_state is omitted on the first call to set_topology, all UTs are treated as indoor UTs. Outdoor-to-indoor penetration loss is not applied by the InF model. TR 38.901 indoor-factory topologies can be generated with gen_tr38901_indoor_factory_topology().

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

Note

InF supports blockage model B only. The Model A parameter tables in Section 7.6.4.1 of [TR38901V1920] define blocker geometry and spatial-correlation distances for UMi, UMa, SMa, RMa, and InH, but not InF. Model B is geometry-driven and Table 7.6.4.2-5 explicitly includes InF blockers such as humans, automated guided vehicles, and industrial robots. Requiring explicit Model B screens avoids introducing unspecified Model A parameters for InF.

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

  • factory_scenario (str) – Indoor-factory sub-scenario. Must be "SL", "DL", "SH", "DH", or "HH". Defaults to "SH".

  • hall_dimensions (tuple[float, float, float] | None) – Optional hall dimensions (length, width, height) [m]. If None, the sub-scenario default described above is used.

  • clutter_density (float | None) – Surface fraction occupied by clutter. If None, the sub-scenario default described above is used.

  • clutter_size (float | None) – Typical clutter size \(d_\mathrm{clutter}\) [m]. If None, the sub-scenario default described above is used.

  • clutter_height (float | None) – Effective clutter height \(h_c\) [m]. If None, the sub-scenario default described above is used.

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

  • enable_spatial_consistency (bool) – If True, additionally generate LoS/NLoS states 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 blockage model B according to Section 7.6.4.2 of [TR38901V1920]. Explicit screen centres, widths, and heights are then required. The optional, on-demand temporal variability of blockage is currently not supported. See Blockage. Defaults to False.

  • blockage_screen_centers – Blockage model B screen centres [m]. Shape [num_blockers, 3] or [batch size, num_blockers, 3].

  • blockage_screen_widths – Blockage model B screen widths [m]. Shape [num_blockers] or [batch size, num_blockers].

  • blockage_screen_heights – Blockage model B screen heights [m]. Shape [num_blockers] or [batch size, num_blockers].

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

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 InF, PanelArray
from sionna.sys import gen_tr38901_indoor_factory_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 = InF(carrier_frequency=carrier_frequency,
                    ut_array=ut_array,
                    bs_array=bs_array,
                    direction='downlink',
                    factory_scenario='SH',
                    device=device)

topology = gen_tr38901_indoor_factory_topology("SH",
                                               batch_size=1,
                                               num_ut=4,
                                               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 accepts the same topology arguments as set_topology(). For convenience, if in_state is omitted while ut_loc is given, all UTs are marked as indoor, because outdoor-to-indoor penetration loss is not applied by the InF model.

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]. If None while ut_loc is provided, all UTs are treated as indoor.

  • los (bool | str | torch.Tensor | None) – LoS/NLoS state control. If set to True, all UTs are forced to be in LoS. If set to False, all 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) – Not applicable to native indoor InF links; providing it raises a ValueError.

  • 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 applicable; InF supports model B only. InF uses one region by default. Shape [num_ut] or [batch size, num_ut].