:orphan:

Metrics
-------

.. currentmodule:: sionna.phy.channel.tr38901

The following functions compute calibration and validation metrics for the
3GPP TR 38.901 channel models :cite:p:`TR38901V1920`.

.. note::

   These helpers are intended only for calibration and verification of the
   channel-model implementation. They are not used to generate channels and
   are not required during normal channel simulation.

Metric Domains
~~~~~~~~~~~~~~

The functions operate at three different levels:

* The weighted-profile functions implement the mathematical spread formulas
  for an already constructed power-delay profile or power-angular spectrum.
* The ray functions construct the propagation-domain profiles used for
  TR 38.901 calibration from :class:`Rays`, :class:`LSP`, and the scenario
  state. They account for the deterministic LOS component and, for delay
  spread, the sub-cluster mapping from Eq. (7.5-26) and Table 7.5-5.
* The PRB function operates on the realized, antenna-dependent complex MIMO
  channel coefficients required by the singular-value calibration metric.

For a scalar channel impulse response

.. math::

   h(\tau) = \sum_n a_n\,\delta(\tau-\tau_n),

an effective RMS delay spread can be obtained by passing
:math:`P_n=|a_n|^2` and :math:`\tau_n` to :func:`rms_delay_spread`. For a MIMO,
time-varying channel, however, this value depends on the selected antenna
ports, antenna patterns, polarization, time sample, and how powers are averaged
over these dimensions. The resulting quantity is an *effective channel* delay
spread. In contrast, :func:`delay_spread_from_rays` computes the
propagation-domain quantity used by the TR 38.901 calibration procedure before
antenna responses and random small-scale phases are applied.

TR 38.901 gives the circular angular-spread expression explicitly in Annex
A.1, Eq. (A-1). It uses RMS delay spread in Clauses 7.7.3 and 7.7.6 and as
a calibration metric in Tables 7.8-2 and 7.8-7, but does not assign the
power-weighted second-central-moment expression a separate equation number.

Weighted-Profile Metrics
~~~~~~~~~~~~~~~~~~~~~~~~

.. autosummary::
   :toctree: .

   rms_delay_spread
   circular_angular_spread

TR 38.901 Ray Metrics
~~~~~~~~~~~~~~~~~~~~~

.. autosummary::
   :toctree: .

   delay_spread_from_rays
   angular_spreads_from_rays

MIMO Channel Metrics
~~~~~~~~~~~~~~~~~~~~

.. autosummary::
   :toctree: .

   prb_singular_values

Related Objects
---------------

The metric helpers operate on the following lower-level objects generated by
the 3GPP TR 38.901 channel model implementation
:cite:p:`TR38901V1920`.

.. autosummary::
   :toctree: .

   Rays
   LSP