EESM#

class sionna.sys.EESM(load_beta_table_from: str = 'default', sinr_eff_min_db: float = -30.0, sinr_eff_max_db: float = 30.0, precision: Literal['single', 'double'] | None = None, device: str | None = None)[source]#

Bases: sionna.sys.effective_sinr.EffectiveSINR

Computes the effective SINR from input SINR values across multiple subcarriers and streams via the exponential effective SINR mapping (EESM) method.

Let \(\mathrm{SINR}_{u,c,s}>0\) be the SINR experienced by user \(u\) on subcarrier \(c=1,\dots,C\), and stream \(s=1,\dots,S_c\). If per_stream is False, it computes the effective SINR aggregated across all utilized streams and subcarriers for each user \(u\):

\[\mathrm{SINR}^{\mathrm{eff}}_u = -\beta_u \log \left( \frac{1}{|\mathcal{R}_u|} \sum_{(c,s)\in\mathcal{R}_u} e^{-\frac{\mathrm{SINR}_{u,c,s}}{\beta_u}} \right), \quad \forall\, u\]

where \(\mathcal{R}_u\) is the set of used (positive-SINR) resource elements for user \(u\) across subcarriers and streams, and \(\beta>0\) is a parameter depending on the Modulation and Coding Scheme (MCS) of user \(u\).

If per_stream is True, it computes the effective SINR aggregated across subcarriers, for each user \(u\) and associated stream \(s\):

\[\mathrm{SINR}^{\mathrm{eff}}_{u,s} = -\beta_u \log \left( \frac{1}{|\mathcal{R}_{u,s}|} \sum_{c\in\mathcal{R}_{u,s}} e^{-\frac{\mathrm{SINR}_{u,c,s}}{\beta_u}} \right), \quad \forall\, u,s.\]
Parameters:

  • load_beta_table_from (str) – File name from which the tables containing the values of \(\beta\) parameters are loaded. If 'default', uses the built-in table.

  • sinr_eff_min_db (float) – Minimum effective SINR value [dB]. Useful to avoid numerical errors. Defaults to -30.

  • sinr_eff_max_db (float) – Maximum effective SINR value [dB]. Useful to avoid numerical errors. Defaults to 30.

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

Inputs:

  • sinr – […, num_ofdm_symbols, num_subcarriers, num_ut, num_streams_per_ut], torch.float. Post-equalization SINR in linear scale for different OFDM symbols, subcarriers, users and streams. If one entry is zero, the corresponding stream is considered as not utilized.

  • mcs_index – […, num_ut], torch.int32. Modulation and coding scheme (MCS) index for each user.

  • mcs_table_index – […, num_ut], torch.int32 (default: 1). MCS table index for each user. The default beta table covers indices {1, 2} only; unsupported indices raise ValueError. Supply a custom beta table, or bypass EESM by passing sinr_eff and num_allocated_re to PHYAbstraction.

  • mcs_category – […, num_ut], torch.int32 (default: None). Accepted for API symmetry with PHYAbstraction. The default beta parameters are category-independent (shared across PUSCH/PDSCH for the same table index) and this argument is unused.

  • per_stream – bool (default: False). If True, then the effective SINR is computed on a per-user and per-stream basis and is aggregated across different subcarriers. If False, then the effective SINR is computed on a per-user basis and is aggregated across streams and subcarriers.

Outputs:

sinr_eff – ([…, num_ut, num_streams_per_ut] | […, num_ut]), torch.float. Effective SINR in linear scale for each user and associated stream. If per_stream is True, then sinr_eff has shape [..., num_ut, num_streams_per_ut], and sinr_eff[..., u, s] is the effective SINR for stream s of user u across all subcarriers. If per_stream is False, then sinr_eff has shape [..., num_ut], and sinr_eff[..., u] is the effective SINR for user u across all streams and subcarriers. Users, or streams, without any used resource are assigned a null effective SINR of exactly 0.

Notes

If the input SINR is zero for a specific stream, the stream is considered unused and does not contribute to the effective SINR computation. The averages above are therefore over used resources only, not over the full C / CS grid.

A user, or stream, whose resources are all unused has no defined effective SINR and is assigned exactly 0, which lies outside the range spanned by sinr_eff_min_db and sinr_eff_max_db. Consumers that treat non-positive values as missing, such as OuterLoopLinkAdaptation, depend on this convention.

Examples

import torch
from sionna.phy import config
from sionna.sys import EESM
from sionna.phy.utils import db_to_lin

batch_size = 10
num_ofdm_symbols = 12
num_subcarriers = 32
num_ut = 15
num_streams_per_ut = 2

# Generate random MCS indices
mcs_index = torch.randint(0, 27, (batch_size, num_ut))

# Instantiate the EESM object
eesm = EESM()

# Generate random SINR values
sinr_db = torch.rand(batch_size, num_ofdm_symbols, num_subcarriers,
                     num_ut, num_streams_per_ut) * 35 - 5
sinr = db_to_lin(sinr_db)

# Compute the effective SINR for each receiver
sinr_eff = eesm(sinr, mcs_index, mcs_table_index=1, per_stream=False)
print(sinr_eff.shape)
# torch.Size([10, 15])

# Compute the per-stream effective SINR for each receiver
sinr_eff_per_stream = eesm(sinr, mcs_index, mcs_table_index=2,
                           per_stream=True)
print(sinr_eff_per_stream.shape)
# torch.Size([10, 15, 2])

Attributes

property beta_table: Dict#

dict (read-only): Maps MCS indices to the corresponding parameters, commonly called \(\beta\), calibrating the Exponential Effective SINR Map (EESM) method. It has the form beta_table['index'][mcs_table_index][mcs].

property beta_table_filenames: List[str]#

str | list of str: Get/set the absolute path name of the JSON file containing the mapping between MCS and EESM beta parameters, stored in beta.

property beta_tensor: torch.Tensor#

[n_tables, n_mcs] (read-only): Tensor corresponding to self.beta_table.

Methods

validate_beta_table() → bool[source]#

Validates the EESM beta parameter dictionary self.beta_table.

Outputs:

is_valid – True if self.beta_table has a valid structure.

Raises:

ValueError – If the structure is invalid.