Demapper#

class sionna.phy.mapping.Demapper(demapping_method: str, constellation_type: str | None = None, num_bits_per_symbol: int | None = None, constellation: sionna.phy.mapping.Constellation | None = None, hard_out: bool = False, precision: Literal['single', 'double'] | None = None, device: str | None = None, **kwargs: Any)[source]#

Bases: sionna.phy.block.Block

Computes log-likelihood ratios (LLRs) or hard-decisions on bits for a tensor of received symbols.

Prior knowledge on the bits can be optionally provided.

This class defines a block implementing different demapping functions. All demapping functions are fully differentiable when soft-decisions are computed.

Parameters:

  • demapping_method (str) – Demapping method. One of “app” or “maxlog”.

  • constellation_type (str | None) – Type of constellation. One of “qam”, “pam”, or “custom”. For “custom”, an instance of Constellation must be provided.

  • num_bits_per_symbol (int | None) – Number of bits per constellation symbol, e.g., 4 for QAM16. Only required for constellation_type in [“qam”, “pam”].

  • constellation (sionna.phy.mapping.Constellation | None) – If no constellation is provided, constellation_type and num_bits_per_symbol must be provided. Defaults to None.

  • hard_out (bool) – If True, the demapper provides hard-decided bits instead of soft-values. Defaults to False.

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

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

  • kwargs (Any)

Inputs:

  • y – […, n], torch.complex. Received symbols.

  • no – Scalar or […, n], torch.float. The noise variance estimate. It can be provided either as scalar for the entire input batch or as a tensor that is “broadcastable” to y.

  • prior – None (default) or [num_bits_per_symbol] or […, num_bits_per_symbol], torch.float. Prior for every bit as LLRs. It can be provided either as a tensor of shape [num_bits_per_symbol] for the entire input batch, or as a tensor that is “broadcastable” to […, n, num_bits_per_symbol].

Outputs:

llr – […, n*num_bits_per_symbol], torch.float. LLRs or hard-decisions for every bit.

Notes

With the “app” demapping method, the LLR for the \(i\text{th}\) bit is computed according to

\[LLR(i) = \ln\left(\frac{\Pr\left(b_i=1\lvert y,\mathbf{p}\right)}{\Pr\left(b_i=0\lvert y,\mathbf{p}\right)}\right) =\ln\left(\frac{ \sum_{c\in\mathcal{C}_{i,1}} \Pr\left(c\lvert\mathbf{p}\right) \exp\left(-\frac{1}{N_o}\left|y-c\right|^2\right) }{ \sum_{c\in\mathcal{C}_{i,0}} \Pr\left(c\lvert\mathbf{p}\right) \exp\left(-\frac{1}{N_o}\left|y-c\right|^2\right) }\right)\]

where \(\mathcal{C}_{i,1}\) and \(\mathcal{C}_{i,0}\) are the sets of constellation points for which the \(i\text{th}\) bit is equal to 1 and 0, respectively. \(\mathbf{p} = \left[p_0,\dots,p_{K-1}\right]\) is the vector of LLRs that serves as prior knowledge on the \(K\) bits that are mapped to a constellation point and is set to \(\mathbf{0}\) if no prior knowledge is assumed to be available, and \(\Pr(c\lvert\mathbf{p})\) is the prior probability on the constellation symbol \(c\):

\[\Pr\left(c\lvert\mathbf{p}\right) = \prod_{k=0}^{K-1} \text{sigmoid}\left(p_k \ell(c)_k\right)\]

where \(\ell(c)_k\) is the \(k^{th}\) bit label of \(c\), where 0 is replaced by -1. The definition of the LLR has been chosen such that it is equivalent with that of logits. This is different from many textbooks in communications, where the LLR is defined as \(LLR(i) = \ln\left(\frac{\Pr\left(b_i=0\lvert y\right)}{\Pr\left(b_i=1\lvert y\right)}\right)\).

With the “maxlog” demapping method, LLRs for the \(i\text{th}\) bit are approximated like

\[\begin{split}\begin{aligned} LLR(i) &\approx\ln\left(\frac{ \max_{c\in\mathcal{C}_{i,1}} \Pr\left(c\lvert\mathbf{p}\right) \exp\left(-\frac{1}{N_o}\left|y-c\right|^2\right) }{ \max_{c\in\mathcal{C}_{i,0}} \Pr\left(c\lvert\mathbf{p}\right) \exp\left(-\frac{1}{N_o}\left|y-c\right|^2\right) }\right)\\ &= \max_{c\in\mathcal{C}_{i,0}} \left(\ln\left(\Pr\left(c\lvert\mathbf{p}\right)\right)-\frac{|y-c|^2}{N_o}\right) - \max_{c\in\mathcal{C}_{i,1}}\left( \ln\left(\Pr\left(c\lvert\mathbf{p}\right)\right) - \frac{|y-c|^2}{N_o}\right) . \end{aligned}\end{split}\]

Examples

import torch
from sionna.phy.mapping import Mapper, Demapper

mapper = Mapper("qam", 4)
demapper = Demapper("app", "qam", 4)

bits = torch.randint(0, 2, (10, 100), dtype=torch.float32)
symbols = mapper(bits)

# Add noise
noise = 0.1 * torch.randn_like(symbols)
y = symbols + noise

# Compute LLRs
llr = demapper(y, no=0.01)
print(llr.shape)
# torch.Size([10, 100])

Attributes

property constellation: sionna.phy.mapping.Constellation#

Constellation used by the Demapper