gen_tr38901_multicell_topology#

sionna.sys.gen_tr38901_multicell_topology(scenario: str, batch_size: int, num_ut_per_sector: int, carrier_frequency: float, num_rings: int = 2, use_3gpp_calibration_defaults: bool = True, isd: float | None = None, bs_height: float | None = None, min_bs_ut_dist: float | None = None, indoor_probability: float | None = None, apply_tr36873_indoor_heights: bool | None = None, return_site_positions: bool = False, enforce_indoor_distance: bool = True, precision: Literal['single', 'double'] | None = None, device: str | None = None) → tuple[source]#

Generates a TR 38.901 multi-cell topology using Tables 7.8-1 and 7.8-2 for UMi/UMa and Table 7.2-3 for RMa of [TR38901V1920].

This helper creates the hexagonal multi-cell topology used for the UMi, UMa, and RMa calibration-style scenarios. By default, it generates a two-ring layout with 19 sites, three co-located sectors per site, wraparound virtual BS locations, and explicit site identifiers for sharing site-level random quantities across co-located sectors.

The sector boresights follow the Table 7.8 convention \(30^\circ\), \(150^\circ\), and \(270^\circ\).

UT locations are generated by a stratified sector drop. For every batch item, site, and sector, exactly num_ut_per_sector UTs are drawn. Each drop region is the actual intersection of a 120-degree sector with its site’s Voronoi hexagon. The intersection is triangulated from the site; triangles are selected in proportion to their area and sampled uniformly with barycentric coordinates. Samples that violate min_bs_ut_dist are rejected and redrawn. Indoor/outdoor state is drawn before the position. For indoor UTs, the rejection distance includes the home-site outdoor-to-indoor distance used by the calibration setup. Thus, the drop enforces equal UT counts per sector and is uniform over each admissible sector/Voronoi intersection.

../../_images/tr38901_multicell_topology.png

Fig. 24 Example one-ring UMi calibration topology with co-located BS sectors and stratified UT drops.#

Parameters:

  • scenario (str) – Scenario. One of "umi", "uma", or "rma".

  • batch_size (int) – Batch size.

  • num_ut_per_sector (int) – Number of UTs to drop per sector and batch.

  • carrier_frequency (float) – Carrier frequency [Hz]. For UMi and UMa below 6 GHz, the indoor distance follows the backward-compatible link-specific single-uniform model from Table 7.4.3-3. At 6 GHz and above, and for RMa, it is the minimum of two independent uniform variables according to Clause 7.4.3.1. Use the same value as for the channel model.

  • num_rings (int) – Number of rings in the hexagonal site layout.

  • use_3gpp_calibration_defaults (bool) – If True, missing topology parameters are filled with TR 38.901 Table 7.8 calibration defaults.

  • isd (float | None) – Inter-site distance [m].

  • bs_height (float | None) – BS height [m].

  • min_bs_ut_dist (float | None) – Minimum 2D BS-UT distance [m]. If None, the standard defaults are 10 m for UMi and 35 m for UMa and RMa.

  • indoor_probability (float | None) – Probability that a UT is indoor. For RMa, the remaining UTs are interpreted as in-car by the channel unless an explicit in_car mask is supplied to set_topology().

  • apply_tr36873_indoor_heights (bool | None) – If True, indoor UMi/UMa UT heights are drawn from the TR 36.873 floor-height model used by the calibration drops. If None, this is enabled for UMi/UMa and disabled for RMa. RMa UT heights are always 1.5 m according to Table 7.2-3.

  • return_site_positions (bool) – If True, return (topology, site_positions) instead of only topology. The topology tuple can still be passed directly to set_topology().

  • enforce_indoor_distance (bool) – If True, include the sampled indoor distance in the placement rejection threshold. This ensures that the outdoor part of every serving link respects min_bs_ut_dist.

  • precision (Literal['single', 'double'] | None) – Precision used for internal calculations and outputs. If set to None, precision is used.

  • device (str | None) – Device for computation. If None, device is used.

Outputs:

  • ut_loc – [batch_size, num_ut, 3], torch.float. UT locations [m].

  • bs_loc – [batch_size, num_sites*3, 3], torch.float. BS sector locations [m].

  • ut_orientations – [batch_size, num_ut, 3], torch.float. UT orientations [radian]. The calibration topology leaves these at zero; Phase-2 calibration applies its UT-orientation distribution separately.

  • bs_orientations – [batch_size, num_sites*3, 3], torch.float. BS sector orientations [radian].

  • ut_velocities – [batch_size, num_ut, 3], torch.float. UT velocity vectors [m/s]. The calibration topology leaves these at zero.

  • in_state – [batch_size, num_ut], torch.bool. Indoor/non-indoor state of UTs. True means indoor. For RMa, the initial set_topology() call interprets every False entry as in-car per Table 7.2-3 unless in_car is supplied explicitly.

  • los – None. Placeholder for stochastic LoS/NLoS sampling by the channel model.

  • bs_virtual_loc – [batch_size, num_sites*3, num_ut, 3], torch.float. Wraparound virtual BS sector locations [m].

  • bs_site_ids – [num_sites*3], torch.int64. Site identifier of each BS sector. Co-located sectors share the same identifier.

  • spatial_consistency_track_ids – None. Placeholder for optional spatial-consistency track identifiers.

  • distance_2d_in – [batch_size, num_ut] or [batch_size, num_sites*3, num_ut], torch.float. Indoor 2D distances [m]. UMi and UMa below 6 GHz return link-specific distances, with one value shared by the three sectors of each site. Other cases return UT-specific distances. Outdoor UTs have zero distance. The home-site value is used for placement rejection.

  • site_positions – [num_sites, 2], torch.float. Site center positions [m]. Returned separately from topology only if return_site_positions is True.

Examples

from sionna.sys import gen_tr38901_multicell_topology

carrier_frequency = 3.5e9
topology = gen_tr38901_multicell_topology(
    "umi", 1, 2, carrier_frequency)
channel_model.set_topology(*topology)