#
# SPDX-FileCopyrightText: Copyright (c) 2021-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
"""Blockage models for 3GPP TR 38.901 system-level channels."""
from typing import Optional, TYPE_CHECKING
import torch
from sionna._validation import check_tensor_all
from sionna.phy.object import Object
from sionna.phy.channel.utils import deg_2_rad, rad_2_deg, wrap_angle_0_360
from sionna.phy.utils import normal, rand
from .spatial_consistency import (
spatial_consistency_correlation_matrix,
spatial_consistency_matrix_sqrt,
)
from .utils import update_topology_buffer
if TYPE_CHECKING:
from .system_level_scenario import SystemLevelScenario
__all__ = ["BlockageModelA", "BlockageModelB"]
[docs]
class BlockageModelA(Object):
r"""Stochastic blockage model A from 3GPP TR 38.901.
This model implements the add-on blockage procedure from Section 7.6.4.1
of :cite:p:`TR38901V1920`. It generates rectangular angular blocking regions
around each UT and returns the corresponding blockage attenuation for the
cluster arrival angles. The LOS/NLOS state of a link is not changed by this
model.
For non-self-blocking regions, the loss for a cluster with azimuth angle
of arrival :math:`\phi_\mathrm{AOA}` and zenith angle of arrival
:math:`\theta_\mathrm{ZOA}` is
.. math::
L_\mathrm{dB}
= -20 \log_{10}\left(
1 - (F_{A_1}+F_{A_2})(F_{Z_1}+F_{Z_2})
\right)
if :math:`|\phi_\mathrm{AOA}-\phi_k|<x_k` and
:math:`|\theta_\mathrm{ZOA}-\theta_k|<y_k`, and zero otherwise. The terms
:math:`F_{A_1}`, :math:`F_{A_2}`, :math:`F_{Z_1}`, and :math:`F_{Z_2}`
follow Eq. (7.6-23) with the signs from Table 7.6.4.1-3 of
:cite:p:`TR38901V1920`. A compliant Model A realization also
includes one self-blocking region. An additional 30 dB loss is added for
clusters inside the selected portrait or landscape region from Table
7.6.4.1-1. The explicit ``"none"`` mode omits this region and is a
non-standard extension.
The non-self-blocker centre angles are generated as all-correlated uniform
random variables over BS links, following Section 7.6.3.4 of
:cite:p:`TR38901V1920`. The specified exponential
correlation :math:`\rho_u` is imposed with a Gaussian copula whose latent
correlation is :math:`\rho_g=2\sin(\pi\rho_u/6)`.
Their spatial correlation distance is 10 m for outdoor UMi, UMa, and RMa
UTs, 5 m for O2I UTs, and 5 m for InH UTs, as specified by
Table 7.6.4.1-4.
Model A is not available for InF because Tables 7.6.4.1-2 and 7.6.4.1-4
provide neither blocker distributions nor spatial-correlation distances
for InF. Use :class:`BlockageModelB` with explicit blocker geometry for
indoor-factory channels.
The optional, on-demand temporal variability of blockage described by TR
38.901 is currently not supported. Blockage attenuation does not evolve
over the time samples of a generated channel realization.
:param scenario: System-level TR 38.901 scenario.
:param self_blocking: Self-blocking mode. Must be ``"portrait"`` or
``"landscape"`` for a compliant Model A realization. The explicit
value ``"none"`` disables self-blocking as a non-standard extension.
:param num_non_self_blockers: Number of non-self-blocking regions. The
default value of 4 follows Section 7.6.4.1 of
:cite:p:`TR38901V1920`.
:param precision: Precision used for internal calculations. If `None`,
the scenario precision is used.
:param device: Device for computation. If `None`, the scenario device is
used.
:input aoa: Cluster azimuth angles of arrival [degree], shape
``[batch size, num_bs, num_ut, num_clusters]``.
:input zoa: Cluster zenith angles of arrival [degree], shape
``[batch size, num_bs, num_ut, num_clusters]``.
:input los_aoa: Optional LOS azimuth angles of arrival [degree], shape
``[batch size, num_bs, num_ut]``.
:input los_zoa: Optional LOS zenith angles of arrival [degree], shape
``[batch size, num_bs, num_ut]``.
:output cluster_loss_db: Blockage attenuation [dB] for each cluster, shape
``[batch size, num_bs, num_ut, num_clusters]``.
:output los_loss_db: Blockage attenuation [dB] for the deterministic LOS
component, or `None` if ``los_aoa`` or ``los_zoa`` is `None`.
"""
_SELF_BLOCKING_PARAMS = {
"portrait": (260.0, 120.0, 100.0, 80.0),
"landscape": (40.0, 160.0, 110.0, 75.0),
}
def __init__(
self,
scenario: "SystemLevelScenario",
self_blocking: str,
num_non_self_blockers: int = 4,
precision: Optional[str] = None,
device: Optional[str] = None,
) -> None:
precision = scenario.precision if precision is None else precision
device = scenario.device if device is None else device
super().__init__(precision=precision, device=device)
if self_blocking is None:
raise ValueError(
"self_blocking must explicitly select 'portrait' or "
"'landscape'; use 'none' only for the non-standard no-self "
"variant"
)
if self_blocking not in ("none", "portrait", "landscape"):
raise ValueError(
"self_blocking must be 'portrait', 'landscape', or 'none'"
)
if not isinstance(num_non_self_blockers, int):
raise TypeError("num_non_self_blockers must be int")
if num_non_self_blockers < 0:
raise ValueError("num_non_self_blockers must be non-negative")
if scenario.scenario_kind not in ("umi", "uma", "rma", "inh"):
raise ValueError(
"Blockage model A is specified for UMi, UMa, RMa, and InH "
"system-level scenarios."
)
self._scenario = scenario
self._self_blocking = self_blocking
self._num_non_self_blockers = num_non_self_blockers
self._matrix_sqrt = None
self._blocker_phi = None
self._blocker_x = None
self._blocker_y = None
if self_blocking == "none":
self._self_blocking_params = None
else:
phi_sb, x_sb, theta_sb, y_sb = self._SELF_BLOCKING_PARAMS[self_blocking]
self._self_blocking_params = (
torch.tensor(phi_sb, dtype=self.dtype, device=self.device),
torch.tensor(x_sb, dtype=self.dtype, device=self.device),
torch.tensor(theta_sb, dtype=self.dtype, device=self.device),
torch.tensor(y_sb, dtype=self.dtype, device=self.device),
)
@property
def self_blocking(self) -> str:
"""Self-blocking mode. One of ``"none"``, ``"portrait"``, or
``"landscape"``. The ``"none"`` mode is non-standard."""
return self._self_blocking
@property
def num_non_self_blockers(self) -> int:
"""Number of non-self-blocking regions."""
return self._num_non_self_blockers
@property
def requires_ray_angles(self) -> bool:
"""`False` because model A computes one loss per cluster."""
return False
def __call__(
self,
aoa: torch.Tensor,
zoa: torch.Tensor,
los_aoa: Optional[torch.Tensor] = None,
los_zoa: Optional[torch.Tensor] = None,
) -> tuple[torch.Tensor, Optional[torch.Tensor]]:
"""Compute cluster and LOS blockage attenuation."""
if self._blocker_phi is None:
self.topology_updated_callback()
cluster_loss = torch.zeros_like(aoa)
if self._num_non_self_blockers > 0:
cluster_loss = cluster_loss + self._non_self_blocking_loss(aoa, zoa)
if self._self_blocking != "none":
cluster_loss = cluster_loss + self._self_blocking_loss(aoa, zoa)
los_loss = None
if los_aoa is not None and los_zoa is not None:
los_loss = torch.zeros_like(los_aoa)
if self._num_non_self_blockers > 0:
los_loss = los_loss + self._non_self_blocking_loss(
los_aoa.unsqueeze(-1), los_zoa.unsqueeze(-1)
).squeeze(-1)
if self._self_blocking != "none":
los_loss = los_loss + self._self_blocking_loss(
los_aoa.unsqueeze(-1), los_zoa.unsqueeze(-1)
).squeeze(-1)
return cluster_loss, los_loss
[docs]
def topology_updated_callback(self) -> None:
"""Sample topology-dependent blockage parameters."""
self._compute_matrix_sqrt()
self._sample_non_self_blockers()
[docs]
def reset_topology(self) -> None:
"""Reset topology-dependent blockage buffers."""
for name in ("_matrix_sqrt", "_blocker_phi", "_blocker_x", "_blocker_y"):
if hasattr(self, name) and name in self._buffers:
del self._buffers[name]
setattr(self, name, None)
[docs]
def allocate_topology_tensors(
self,
batch_size: int,
num_bs: int,
num_ut: int,
) -> None:
"""Pre-allocate topology-dependent blockage buffers.
Model A samples one blocker realization per UT and shares it across
base stations. ``num_bs`` is retained for the common channel-allocation
interface but does not determine a buffer dimension here.
"""
_ = num_bs
self.reset_topology()
for name in ("_matrix_sqrt", "_blocker_phi", "_blocker_x", "_blocker_y"):
if hasattr(self, name) and name not in self._buffers:
delattr(self, name)
blocker_shape = (batch_size, num_ut, self._num_non_self_blockers)
self.register_buffer(
"_matrix_sqrt",
torch.zeros(
batch_size,
num_ut,
num_ut,
dtype=self.dtype,
device=self.device,
),
)
self.register_buffer(
"_blocker_phi",
torch.zeros(blocker_shape, dtype=self.dtype, device=self.device),
)
self.register_buffer(
"_blocker_x",
torch.zeros(blocker_shape, dtype=self.dtype, device=self.device),
)
self.register_buffer(
"_blocker_y",
torch.zeros(blocker_shape, dtype=self.dtype, device=self.device),
)
def _scenario_is_indoor_hotspot(self) -> bool:
"""Return `True` for InH scenarios."""
return self._scenario.scenario_kind == "inh"
def _blockage_states(self) -> torch.Tensor:
"""UT-state labels for blockage spatial consistency."""
scenario = self._scenario
if self._scenario_is_indoor_hotspot():
states = torch.zeros(
(scenario.batch_size, scenario.num_ut),
dtype=torch.int64,
device=self.device,
)
else:
indoor = scenario.indoor & bool(scenario.o2i_pathloss_enabled)
states = indoor.to(dtype=torch.int64)
return states + 2 * scenario.ut_spatial_region_ids
def _blockage_correlation_distance(self) -> torch.Tensor:
"""Correlation distance from Table 7.6.4.1-4."""
scenario = self._scenario
if self._scenario_is_indoor_hotspot():
return torch.full(
(scenario.batch_size, scenario.num_ut),
5.0,
dtype=self.dtype,
device=self.device,
)
return torch.where(
scenario.indoor & bool(scenario.o2i_pathloss_enabled),
torch.tensor(5.0, dtype=self.dtype, device=self.device),
torch.tensor(10.0, dtype=self.dtype, device=self.device),
)
def _compute_matrix_sqrt(self) -> None:
"""Compute the latent-Gaussian UT-domain spatial filter."""
scenario = self._scenario
uniform_correlation = spatial_consistency_correlation_matrix(
scenario.matrix_ut_distance_2d,
self._blockage_correlation_distance(),
states=self._blockage_states(),
correlation_distance_layout="per_terminal",
precision=self.precision,
device=self.device,
)
gaussian_correlation = 2.0 * torch.sin(
(torch.pi / 6.0) * uniform_correlation
)
gaussian_correlation = gaussian_correlation.clamp(-1.0, 1.0)
matrix_sqrt = spatial_consistency_matrix_sqrt(
gaussian_correlation,
precision=self.precision,
device=self.device,
)
self._update_buffer("_matrix_sqrt", matrix_sqrt)
def _spatial_uniform(self, shape: tuple[int, ...]) -> torch.Tensor:
"""Generate all-correlated uniform random variables over UTs."""
samples = normal(
shape,
dtype=self.dtype,
device=self.device,
generator=self.torch_rng,
)
batch_size, num_ut = samples.shape[:2]
tail_shape = samples.shape[2:]
samples = samples.reshape(batch_size, num_ut, -1)
samples = torch.matmul(self._matrix_sqrt, samples)
samples = samples.reshape(batch_size, num_ut, *tail_shape)
sqrt_two = torch.sqrt(
torch.tensor(2.0, dtype=self.dtype, device=self.device)
)
samples = 0.5 * torch.erfc(-samples / sqrt_two)
eps = torch.finfo(self.dtype).eps
return samples.clamp(eps, 1.0 - eps)
def _sample_non_self_blockers(self) -> None:
"""Sample non-self-blocking regions from Table 7.6.4.1-2."""
scenario = self._scenario
shape = (scenario.batch_size, scenario.num_ut, self._num_non_self_blockers)
if self._num_non_self_blockers == 0:
empty = torch.empty(shape, dtype=self.dtype, device=self.device)
self._update_buffer("_blocker_phi", empty)
self._update_buffer("_blocker_x", empty)
self._update_buffer("_blocker_y", empty)
return
phi = 360.0 * self._spatial_uniform(shape)
if self._scenario_is_indoor_hotspot():
x = 15.0 + 30.0 * rand(
shape,
dtype=self.dtype,
device=self.device,
generator=self.torch_rng,
)
y = 5.0 + 10.0 * rand(
shape,
dtype=self.dtype,
device=self.device,
generator=self.torch_rng,
)
else:
x = 5.0 + 10.0 * rand(
shape,
dtype=self.dtype,
device=self.device,
generator=self.torch_rng,
)
y = torch.full(shape, 5.0, dtype=self.dtype, device=self.device)
self._update_buffer("_blocker_phi", phi)
self._update_buffer("_blocker_x", x)
self._update_buffer("_blocker_y", y)
def _update_buffer(self, name: str, value: torch.Tensor) -> None:
"""Update or register a topology-dependent buffer."""
update_topology_buffer(self, name, value)
@staticmethod
def _unit_sphere_vector(theta: torch.Tensor, phi: torch.Tensor) -> torch.Tensor:
"""Vector on the TR 38.901 unit sphere."""
return torch.stack(
[
torch.sin(theta) * torch.cos(phi),
torch.sin(theta) * torch.sin(phi),
torch.cos(theta),
],
dim=-1,
).unsqueeze(-1)
@staticmethod
def _forward_rotation_matrix(orientations: torch.Tensor) -> torch.Tensor:
"""Forward composite rotation matrix from Eq. (7.1-4)."""
a, b, c = orientations[..., 0], orientations[..., 1], orientations[..., 2]
row_1 = torch.stack(
[
torch.cos(a) * torch.cos(b),
torch.cos(a) * torch.sin(b) * torch.sin(c)
- torch.sin(a) * torch.cos(c),
torch.cos(a) * torch.sin(b) * torch.cos(c)
+ torch.sin(a) * torch.sin(c),
],
dim=-1,
)
row_2 = torch.stack(
[
torch.sin(a) * torch.cos(b),
torch.sin(a) * torch.sin(b) * torch.sin(c)
+ torch.cos(a) * torch.cos(c),
torch.sin(a) * torch.sin(b) * torch.cos(c)
- torch.cos(a) * torch.sin(c),
],
dim=-1,
)
row_3 = torch.stack(
[
-torch.sin(b),
torch.cos(b) * torch.sin(c),
torch.cos(b) * torch.cos(c),
],
dim=-1,
)
return torch.stack([row_1, row_2, row_3], dim=-2)
def _gcs_to_lcs(
self, orientations: torch.Tensor, theta: torch.Tensor, phi: torch.Tensor
) -> tuple[torch.Tensor, torch.Tensor]:
"""Transform GCS angles to LCS angles following Eqs. (7.1-7)-(7.1-8)."""
rho_hat = self._unit_sphere_vector(theta, phi)
rot_inv = self._forward_rotation_matrix(orientations).mT
rot_rho = torch.matmul(rot_inv, rho_hat)
z = rot_rho[..., 2, 0].clamp(-1.0, 1.0)
theta_prime = torch.acos(z)
xy = torch.complex(rot_rho[..., 0, 0], rot_rho[..., 1, 0])
phi_prime = torch.angle(xy)
return theta_prime, phi_prime
@staticmethod
def _signed_angular_difference_deg(
angle: torch.Tensor, reference: torch.Tensor
) -> torch.Tensor:
"""Signed circular difference in degrees within ``[-180, 180)``."""
return torch.remainder(angle - reference + 180.0, 360.0) - 180.0
def _self_blocking_loss(
self, aoa: torch.Tensor, zoa: torch.Tensor
) -> torch.Tensor:
"""Compute the optional self-blocking loss."""
phi_sb, x_sb, theta_sb, y_sb = self._self_blocking_params
scenario = self._scenario
orientations = scenario.ut_orientations.unsqueeze(1)
while orientations.dim() < aoa.dim() + 1:
orientations = orientations.unsqueeze(-2)
theta_prime, phi_prime = self._gcs_to_lcs(
orientations,
deg_2_rad(zoa),
deg_2_rad(aoa),
)
theta_prime = rad_2_deg(theta_prime)
phi_prime = wrap_angle_0_360(rad_2_deg(phi_prime))
phi_diff = torch.abs(
self._signed_angular_difference_deg(
phi_prime,
phi_sb,
)
)
theta_diff = torch.abs(theta_prime - theta_sb)
blocked = (phi_diff < 0.5 * x_sb) & (theta_diff < 0.5 * y_sb)
return torch.where(
blocked,
torch.tensor(30.0, dtype=self.dtype, device=self.device),
torch.zeros((), dtype=self.dtype, device=self.device),
)
def _non_self_parameters(self, ndim: int) -> tuple[torch.Tensor, ...]:
"""Broadcast non-self-blocker parameters."""
phi = self._blocker_phi
x = self._blocker_x
y = self._blocker_y
# [batch, ut, blocker] -> [batch, 1, ut, 1, blocker]
phi = phi.unsqueeze(1).unsqueeze(3)
x = x.unsqueeze(1).unsqueeze(3)
y = y.unsqueeze(1).unsqueeze(3)
while phi.dim() < ndim:
phi = phi.unsqueeze(3)
x = x.unsqueeze(3)
y = y.unsqueeze(3)
return phi, x, y
def _non_self_blocking_loss(
self, aoa: torch.Tensor, zoa: torch.Tensor
) -> torch.Tensor:
"""Compute non-self-blocking loss from Eqs. (7.6-22)-(7.6-27)."""
phi_k, x_k, y_k = self._non_self_parameters(aoa.dim() + 1)
theta_k = torch.tensor(90.0, dtype=self.dtype, device=self.device)
r = torch.tensor(
2.0 if self._scenario_is_indoor_hotspot() else 10.0,
dtype=self.dtype,
device=self.device,
)
wavelength = self._scenario.lambda_0
aoa = aoa.unsqueeze(-1)
zoa = zoa.unsqueeze(-1)
phi_delta = self._signed_angular_difference_deg(aoa, phi_k)
theta_delta = zoa - theta_k
active = (torch.abs(phi_delta) < x_k) & (torch.abs(theta_delta) < y_k)
a1 = phi_delta - 0.5 * x_k
a2 = phi_delta + 0.5 * x_k
z1 = theta_delta - 0.5 * y_k
z2 = theta_delta + 0.5 * y_k
sign_a1 = torch.where(
phi_delta > 0.5 * x_k,
torch.tensor(-1.0, dtype=self.dtype, device=self.device),
torch.tensor(1.0, dtype=self.dtype, device=self.device),
)
sign_a2 = torch.where(
phi_delta < -0.5 * x_k,
torch.tensor(-1.0, dtype=self.dtype, device=self.device),
torch.tensor(1.0, dtype=self.dtype, device=self.device),
)
sign_z1 = torch.where(
theta_delta > 0.5 * y_k,
torch.tensor(-1.0, dtype=self.dtype, device=self.device),
torch.tensor(1.0, dtype=self.dtype, device=self.device),
)
sign_z2 = torch.where(
theta_delta < -0.5 * y_k,
torch.tensor(-1.0, dtype=self.dtype, device=self.device),
torch.tensor(1.0, dtype=self.dtype, device=self.device),
)
f_a1 = self._knife_edge_term(a1, sign_a1, r, wavelength)
f_a2 = self._knife_edge_term(a2, sign_a2, r, wavelength)
f_z1 = self._knife_edge_term(z1, sign_z1, r, wavelength)
f_z2 = self._knife_edge_term(z2, sign_z2, r, wavelength)
product = (f_a1 + f_a2) * (f_z1 + f_z2)
eps = torch.finfo(self.dtype).eps
argument = (1.0 - product).clamp_min(eps)
loss = -20.0 * torch.log10(argument)
loss = torch.where(active, loss, torch.zeros_like(loss))
return loss.sum(dim=-1)
def _knife_edge_term(
self,
angle_deg: torch.Tensor,
sign: torch.Tensor,
r: torch.Tensor,
wavelength: torch.Tensor,
) -> torch.Tensor:
"""Term from Eq. (7.6-23)."""
angle_rad = deg_2_rad(angle_deg)
cos_angle = torch.cos(angle_rad).clamp_min(torch.finfo(self.dtype).eps)
radicand = (torch.pi / wavelength) * r * (1.0 / cos_angle - 1.0)
radicand = radicand.clamp_min(0.0)
return torch.atan(sign * 0.5 * torch.pi * torch.sqrt(radicand)) / torch.pi
[docs]
class BlockageModelB(Object):
r"""Geometric blockage model B from 3GPP TR 38.901.
This model implements the rectangular-screen blockage add-on from Section
7.6.4.2 of :cite:p:`TR38901V1920`. A set of physical blocker screens is placed
in the global coordinate system. For every sub-path, the screen is rotated
around its centre such that the incoming ray is perpendicular to the screen
and the loss is computed from the simple knife-edge diffraction model
.. math::
L_\mathrm{dB}
= -20 \log_{10}\left(
1 - (F_{h_1}+F_{h_2})(F_{w_1}+F_{w_2})
\right)
where the four :math:`F` terms follow Eq. (7.6-30) of
:cite:p:`TR38901V1920`. Losses from multiple screens are summed in dB. The
LOS/NLOS state of each link is not changed by this model.
The positions and dimensions of the blockers are simulation assumptions.
Recommended dimensions for humans, vehicles, AGVs, and industrial robots
are listed in Table 7.6.4.2-5 of :cite:p:`TR38901V1920`.
The optional, on-demand temporal variability of blockage described by TR
38.901 is currently not supported. Blockage attenuation does not evolve
over the time samples of a generated channel realization.
When used with
:class:`~sionna.phy.channel.tr38901.ChannelCoefficientsGenerator`, the
returned losses are applied as per-ray amplitude factors
:math:`10^{-L_\mathrm{dB}/20}` before the channel paths are coherently
summed. This convention is also used by the bundled blockage Model B RSRP
calibration curves.
:param scenario: System-level TR 38.901 scenario.
:param blocker_centers: Blocker screen centres [m], shape
``[num_blockers, 3]`` or ``[batch size, num_blockers, 3]``.
:param blocker_widths: Blocker widths [m], shape ``[num_blockers]`` or
``[batch size, num_blockers]``.
:param blocker_heights: Blocker heights [m], shape ``[num_blockers]`` or
``[batch size, num_blockers]``.
:param precision: Precision used for internal calculations. If `None`,
the scenario precision is used.
:param device: Device for computation. If `None`, the scenario device is
used.
:input aoa: Ray azimuth angles of arrival [degree], shape
``[batch size, num_bs, num_ut, num_clusters, num_rays]``.
:input zoa: Ray zenith angles of arrival [degree], shape
``[batch size, num_bs, num_ut, num_clusters, num_rays]``.
:input los_aoa: Optional LOS azimuth angles of arrival [degree], shape
``[batch size, num_bs, num_ut]``.
:input los_zoa: Optional LOS zenith angles of arrival [degree], shape
``[batch size, num_bs, num_ut]``.
:output ray_loss_db: Blockage attenuation [dB] for each ray, shape
``[batch size, num_bs, num_ut, num_clusters, num_rays]``.
:output los_loss_db: Blockage attenuation [dB] for the deterministic LOS
component, or `None` if ``los_aoa`` or ``los_zoa`` is `None`.
"""
def __init__(
self,
scenario: "SystemLevelScenario",
blocker_centers: torch.Tensor,
blocker_widths: torch.Tensor,
blocker_heights: torch.Tensor,
precision: Optional[str] = None,
device: Optional[str] = None,
) -> None:
precision = scenario.precision if precision is None else precision
device = scenario.device if device is None else device
super().__init__(precision=precision, device=device)
self._scenario = scenario
centers = torch.as_tensor(blocker_centers, dtype=self.dtype, device=self.device)
widths = torch.as_tensor(blocker_widths, dtype=self.dtype, device=self.device)
heights = torch.as_tensor(blocker_heights, dtype=self.dtype, device=self.device)
if centers.dim() == 2:
centers = centers.unsqueeze(0)
if centers.dim() != 3 or centers.shape[-1] != 3:
raise ValueError(
"blocker_centers must have shape [num_blockers, 3] or "
"[batch size, num_blockers, 3]"
)
if widths.dim() == 1:
widths = widths.unsqueeze(0)
if heights.dim() == 1:
heights = heights.unsqueeze(0)
if widths.dim() != 2 or heights.dim() != 2:
raise ValueError(
"blocker_widths and blocker_heights must have shape "
"[num_blockers] or [batch size, num_blockers]"
)
if (
widths.shape[-1] != centers.shape[-2]
or heights.shape[-1] != centers.shape[-2]
):
raise ValueError(
"blocker_widths and blocker_heights must match the number of "
"blocker_centers"
)
batch_dims = (centers.shape[0], widths.shape[0], heights.shape[0])
max_batch_dim = max(batch_dims)
if any(dim not in (1, max_batch_dim) for dim in batch_dims):
raise ValueError(
"Batch dimensions of blocker_centers, blocker_widths, and "
"blocker_heights are inconsistent"
)
check_tensor_all(
(widths > 0.0) & (heights > 0.0),
name="blocker dimensions",
message="blocker widths and heights must be positive",
)
self.register_buffer("_blocker_centers", centers)
self.register_buffer("_blocker_widths", widths)
self.register_buffer("_blocker_heights", heights)
@property
def requires_ray_angles(self) -> bool:
"""`True` because model B computes one loss per ray."""
return True
@property
def num_blockers(self) -> int:
"""Number of configured blocker screens."""
return self._blocker_centers.shape[-2]
def __call__(
self,
aoa: torch.Tensor,
zoa: torch.Tensor,
los_aoa: Optional[torch.Tensor] = None,
los_zoa: Optional[torch.Tensor] = None,
) -> tuple[torch.Tensor, Optional[torch.Tensor]]:
"""Compute ray and LOS blockage attenuation."""
if aoa.dim() != 5 or zoa.shape != aoa.shape:
raise ValueError(
"Model B expects ray angles with shape "
"[batch size, num_bs, num_ut, num_clusters, num_rays]"
)
ray_loss = self._screen_loss(aoa, zoa, direct_path=False)
los_loss = None
if los_aoa is not None and los_zoa is not None:
los_loss = self._screen_loss(
los_aoa.unsqueeze(-1).unsqueeze(-1),
los_zoa.unsqueeze(-1).unsqueeze(-1),
direct_path=True,
).squeeze(-1).squeeze(-1)
return ray_loss, los_loss
[docs]
def topology_updated_callback(self) -> None:
"""Model B blocker geometry is explicit and topology-independent."""
[docs]
def reset_topology(self) -> None:
"""Model B has no topology-dependent random buffers."""
def _blockers_for_batch(self, batch_size: int) -> tuple[torch.Tensor, ...]:
"""Return blocker geometry broadcast to ``batch_size``."""
centers = self._blocker_centers
widths = self._blocker_widths
heights = self._blocker_heights
if centers.shape[0] == 1 and batch_size != 1:
centers = centers.expand(batch_size, -1, -1)
if widths.shape[0] == 1 and batch_size != 1:
widths = widths.expand(batch_size, -1)
if heights.shape[0] == 1 and batch_size != 1:
heights = heights.expand(batch_size, -1)
if (
centers.shape[0] != batch_size
or widths.shape[0] != batch_size
or heights.shape[0] != batch_size
):
raise ValueError(
"Batch-specific blocker geometry must match the current "
"topology batch size"
)
return centers, widths, heights
@staticmethod
def _unit_sphere_vector(theta: torch.Tensor, phi: torch.Tensor) -> torch.Tensor:
"""Vector on the TR 38.901 unit sphere."""
return torch.stack(
[
torch.sin(theta) * torch.cos(phi),
torch.sin(theta) * torch.sin(phi),
torch.cos(theta),
],
dim=-1,
)
def _screen_loss(
self,
aoa: torch.Tensor,
zoa: torch.Tensor,
direct_path: bool,
) -> torch.Tensor:
"""Compute total loss from all screens."""
scenario = self._scenario
batch_size = aoa.shape[0]
centers, widths, heights = self._blockers_for_batch(batch_size)
ray_dir = self._unit_sphere_vector(deg_2_rad(zoa), deg_2_rad(aoa))
ray_dir = ray_dir.unsqueeze(-2)
rx = scenario.ut_loc[:, None, :, None, None, None, :]
tx = scenario.bs_virtual_loc[:, :, :, None, None, None, :]
centers = centers[:, None, None, None, None, :, :]
widths = widths[:, None, None, None, None, :]
heights = heights[:, None, None, None, None, :]
loss_top = self._projected_loss(
ray_dir,
rx,
tx,
centers,
widths,
direct_path=direct_path,
projection="top",
)
loss_side = self._projected_loss(
ray_dir,
rx,
tx,
centers,
heights,
direct_path=direct_path,
projection="side",
)
product = loss_side["f_sum"] * loss_top["f_sum"]
eps = torch.finfo(self.dtype).eps
loss = -20.0 * torch.log10((1.0 - product).clamp_min(eps))
active = loss_side["active"] & loss_top["active"]
loss = torch.where(active, loss, torch.zeros_like(loss))
return loss.sum(dim=-1)
def _projected_loss(
self,
ray_dir: torch.Tensor,
rx: torch.Tensor,
tx: torch.Tensor,
centers: torch.Tensor,
size: torch.Tensor,
direct_path: bool,
projection: str,
) -> dict[str, torch.Tensor]:
"""Compute projected knife-edge terms for one screen dimension."""
eps = torch.finfo(self.dtype).eps
if projection == "top":
norm_xy = torch.linalg.norm(ray_dir[..., :2], dim=-1).clamp_min(eps)
u = ray_dir[..., :2] / norm_xy.unsqueeze(-1)
v = torch.stack([-u[..., 1], u[..., 0]], dim=-1)
rel = centers[..., :2] - rx[..., :2]
center_parallel = (rel * u).sum(dim=-1)
center_offset = (rel * v).sum(dim=-1)
if direct_path:
tx_rel = tx[..., :2] - rx[..., :2]
tx_parallel = (tx_rel * u).sum(dim=-1)
tx_offset = (tx_rel * v).sum(dim=-1)
path_length = torch.sqrt(tx_parallel.square() + tx_offset.square())
else:
tx_parallel = None
tx_offset = None
path_length = None
elif projection == "side":
norm_xy = torch.linalg.norm(ray_dir[..., :2], dim=-1).clamp_min(eps)
u_parallel = norm_xy
u_vertical = ray_dir[..., 2]
rel_xy = centers[..., :2] - rx[..., :2]
horizontal_dir = ray_dir[..., :2] / norm_xy.unsqueeze(-1)
rel_horizontal = (rel_xy * horizontal_dir).sum(dim=-1)
rel_vertical = centers[..., 2] - rx[..., 2]
center_parallel = (
rel_horizontal * u_parallel + rel_vertical * u_vertical
)
center_offset = (
-rel_horizontal * u_vertical + rel_vertical * u_parallel
)
if direct_path:
tx_rel_xy = tx[..., :2] - rx[..., :2]
tx_horizontal = (tx_rel_xy * horizontal_dir).sum(dim=-1)
tx_vertical = tx[..., 2] - rx[..., 2]
tx_parallel = tx_horizontal * u_parallel + tx_vertical * u_vertical
tx_offset = -tx_horizontal * u_vertical + tx_vertical * u_parallel
path_length = torch.sqrt(tx_parallel.square() + tx_offset.square())
else:
tx_parallel = None
tx_offset = None
path_length = None
else:
raise ValueError("projection must be 'top' or 'side'")
edge_1 = center_offset - 0.5 * size
edge_2 = center_offset + 0.5 * size
d1_1 = torch.sqrt(center_parallel.square() + edge_1.square())
d1_2 = torch.sqrt(center_parallel.square() + edge_2.square())
intersects = torch.abs(center_offset) <= 0.5 * size
if direct_path:
d2_1 = torch.sqrt((tx_parallel - center_parallel).square()
+ (tx_offset - edge_1).square())
d2_2 = torch.sqrt((tx_parallel - center_parallel).square()
+ (tx_offset - edge_2).square())
excess_1 = d1_1 + d2_1 - path_length
excess_2 = d1_2 + d2_2 - path_length
sign_metric_1 = d1_1 + d2_1
sign_metric_2 = d1_2 + d2_2
between_endpoints = (
(center_parallel > 0.0)
& (center_parallel < path_length.clamp_min(eps))
)
active = between_endpoints
else:
excess_1 = d1_1 - center_parallel
excess_2 = d1_2 - center_parallel
sign_metric_1 = d1_1
sign_metric_2 = d1_2
active = center_parallel > 0.0
sign_1 = torch.where(
intersects | (sign_metric_1 > sign_metric_2),
torch.tensor(1.0, dtype=self.dtype, device=self.device),
torch.tensor(-1.0, dtype=self.dtype, device=self.device),
)
sign_2 = torch.where(
intersects | (sign_metric_2 > sign_metric_1),
torch.tensor(1.0, dtype=self.dtype, device=self.device),
torch.tensor(-1.0, dtype=self.dtype, device=self.device),
)
f_1 = self._knife_edge_term(excess_1, sign_1)
f_2 = self._knife_edge_term(excess_2, sign_2)
return {"f_sum": f_1 + f_2, "active": active}
def _knife_edge_term(
self,
excess_distance: torch.Tensor,
sign: torch.Tensor,
) -> torch.Tensor:
"""Knife-edge term from Eq. (7.6-30)."""
radicand = (torch.pi / self._scenario.lambda_0) * excess_distance
radicand = radicand.clamp_min(0.0)
return torch.atan(sign * 0.5 * torch.pi * torch.sqrt(radicand)) / torch.pi