Mapping

class sionna.phy.mapping.Constellation(constellation_type, num_bits_per_symbol, points=None, normalize=False, center=False, precision=None, **kwargs)

Constellation that can be used by a (de-)mapper

This class defines a constellation, i.e., a complex-valued vector of constellation points. The binary representation of the index of an element of this vector corresponds to the bit label of the constellation point. This implicit bit labeling is used by the Mapper and Demapper.

Parameters:

• constellation_type ("qam" | "pam" | "custom") – For “custom”, the constellation points must be provided.

• num_bits_per_symbol (int) – Number of bits per constellation symbol, e.g., 4 for QAM16.

• points (None (default) | [2**num_bits_per_symbol], array_like) – Custom constellation points

• normalize (bool, (default False)) – If True, the constellation is normalized to have unit power. Only applies to custom constellations.

• center (bool, (default False)) – If True, the constellation is ensured to have zero mean. Only applies to custom constellations.

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs. If set to None, precision is used.

Input:

None

Output:

[2**num_bits_per_symbol], tf.complex – (Possibly) centered and normalized constellation points

property center

Get/set if the constellation is centered

Type:

bool

property constellation_type

Constellation type

Type:

“qam” | “pam” | “custom”

property normalize

Get/set if the constellation is normalized

Type:

bool

property num_bits_per_symbol

Number of bits per symbol

Type:

int

property num_points

Number of constellation points

Type:

int

property points

Get/set constellation points

Type:

[2**num_bits_per_symbol], tf.complex

show(labels=True, figsize=(7, 7))

Generate a scatter-plot of the constellation

Input:

• labels (bool, (default True)) – If True, the bit labels will be drawn next to each constellation point.

• figsize (Two-element Tuple, float, (default (7,7))) – Width and height in inches

Output:

matplotlib.figure.Figure – Handle to matplot figure object

class sionna.phy.mapping.Mapper(constellation_type=None, num_bits_per_symbol=None, constellation=None, return_indices=False, precision=None, **kwargs)

Maps binary tensors to points of a constellation

This class defines a block that maps a tensor of binary values to a tensor of points from a provided constellation.

Parameters:

• constellation_type ("qam" | "pam" | "custom") – For “custom”, an instance of Constellation must be provided.

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

• constellation (None (default) | Constellation) – If no constellation is provided, constellation_type and num_bits_per_symbol must be provided.

• return_indices (bool, (default False)) – If enabled, symbol indices are additionally returned.

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs. If set to None, precision is used.

Input:

[…, n], tf.float or tf.int – Tensor with with binary entries

Output:

• […,n/Constellation.num_bits_per_symbol], tf.complex – Mapped constellation symbols

• […,n/Constellation.num_bits_per_symbol], tf.int32 – Symbol indices corresponding to the constellation symbols. Only returned if return_indices is set to True.

Note

The last input dimension must be an integer multiple of the number of bits per constellation symbol.

property constellation

Constellation used by the Mapper

Type:

Constellation

class sionna.phy.mapping.Demapper(demapping_method, constellation_type=None, num_bits_per_symbol=None, constellation=None, hard_out=False, precision=None, **kwargs)

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 ("app" | "maxlog") – Demapping method

• constellation_type ("qam" | "pam" | "custom") – For “custom”, an instance of Constellation must be provided.

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

• constellation (None (default) | Constellation) – If no constellation is provided, constellation_type and num_bits_per_symbol must be provided.

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

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs. If set to None, precision is used.

Input:

• y ([…,n], tf.complex) – Received symbols

• no (Scalar or […,n], tf.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) | [num_bits_per_symbol] or […,num_bits_per_symbol], tf.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].

Output:

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

Note

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

$$LLR(i)=\ln \left(\frac{Pr(b_i=1|y,\mathbf{p})}{Pr(b_i=0|y,\mathbf{p})}\right)=\ln \left(\frac{\sum _{c\in {\mathcal{C}}_{i,1}}Pr(c|\mathbf{p})\exp (-\frac{1}{N_o}{|y-c|}^2)}{\sum _{c\in {\mathcal{C}}_{i,0}}Pr(c|\mathbf{p})\exp (-\frac{1}{N_o}{|y-c|}^2)}\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}=[p_0,\dots ,p_{K-1}]$ 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|\mathbf{p})$ is the prior probability on the constellation symbol $c$:

$$Pr(c|\mathbf{p})=\prod _{k=0}^{K-1}\text{sigmoid}(p_k\ell (c{)}_k)$$

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(b_i=0|y)}{Pr(b_i=1|y)}\right)$.

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

$$\begin{array}{r}\begin{array}{rl}LLR(i)& \approx \ln \left(\frac{\underset{c\in {\mathcal{C}}_{i,1}}{max}Pr(c|\mathbf{p})\exp (-\frac{1}{N_o}{|y-c|}^2)}{\underset{c\in {\mathcal{C}}_{i,0}}{max}Pr(c|\mathbf{p})\exp (-\frac{1}{N_o}{|y-c|}^2)}\right)\\ & =\underset{c\in {\mathcal{C}}_{i,0}}{max}(\ln (Pr(c|\mathbf{p}))-\frac{|y-c{|}^2}{N_o})-\underset{c\in {\mathcal{C}}_{i,1}}{max}(\ln (Pr(c|\mathbf{p}))-\frac{|y-c{|}^2}{N_o}).\end{array}\end{array}$$

property constellation

Constellation used by the Demapper

Type:

Constellation

class sionna.phy.mapping.SymbolDemapper(constellation_type=None, num_bits_per_symbol=None, constellation=None, hard_out=False, precision=None, **kwargs)

Computes normalized log-probabilities (logits) or hard-decisions on symbols for a tensor of received symbols

Prior knowldge on the transmitted constellation points can be optionnaly provided. The demapping function is fully differentiable when soft-values are computed.

Parameters:

• constellation_type ("qam" | "pam" | "custom") – For “custom”, an instance of Constellation must be provided.

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

• constellation (None (default) | Constellation) – If no constellation is provided, constellation_type and num_bits_per_symbol must be provided.

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

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs. If set to None, precision is used.

Input:

• y ([…,n], tf.complex) – Received symbols

• no (Scalar or […,n], tf.float) – 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) | [num_points] or […,num_points], tf.float) – Prior for every symbol as log-probabilities (logits). It can be provided either as a tensor of shape [num_points] for the entire input batch, or as a tensor that is “broadcastable” to […, n, num_points].

Output:

[…,n, num_points] or […,n], tf.float or tf.int32 – A tensor of shape […,n, num_points] of logits for every constellation point if hard_out is set to False. Otherwise, a tensor of shape […,n] of hard-decisions on the symbols.

Note

The normalized log-probability for the constellation point $c$ is computed according to

$$\ln (Pr(c|y,\mathbf{p}))=\ln \left(\frac{\exp (-\frac{|y-c{|}^2}{N_0}+p_c)}{\sum _{c^{\prime }\in \mathcal{C}}\exp (-\frac{|y-c^{\prime }{|}^2}{N_0}+p_{c^{\prime }})}\right)$$

where $\mathcal{C}$ is the set of constellation points used for modulation, and $\mathbf{p}=\{p_c|c\in \mathcal{C}\}$ the prior information on constellation points given as log-probabilities and which is set to $\mathbf{0}$ if no prior information on the constellation points is assumed to be available.

Utility Functions

class sionna.phy.mapping.BinarySource(precision=None, seed=None, **kwargs)

Generates a random binary tensor

Parameters:

• seed (None (default) | int) – Set the seed for the random generator used to generate the bits. If set to None, tf_rng is used.

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs. If set to None, precision is used.

Input:

shape (1D tensor/array/list, int) – Desired shape of the output tensor

Output:

shape, tf.float – Tensor filled with random binary values

class sionna.phy.mapping.LLRs2SymbolLogits(num_bits_per_symbol, hard_out=False, precision=None, **kwargs)

Computes logits (i.e., unnormalized log-probabilities) or hard decisions on constellation points from a tensor of log-likelihood ratios (LLRs) on bits

Parameters:

• num_bits_per_symbol (int) – Number of bits per constellation symbol, e.g., 4 for QAM16.

• hard_out (bool, (default False)) – If True, the layer provides hard-decided constellation points instead of soft-values.

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs. If set to None, precision is used.

Input:

llrs ([…, n, num_bits_per_symbol], tf.float) – LLRs for every bit

Output:

[…,n, num_points], tf.float or […, n], tf.int32 – Logits or hard-decisions on constellation points

Note

The logit for the constellation $c$ point is computed according to

$$\begin{array}{r}\begin{array}{rl}\log (Pr(c|LLRs))& =\log (\prod _{k=0}^{K-1}Pr(b_k=\ell (c{)}_k|LLRs))\\ & =\log \left(\prod _{k=0}^{K-1}\text{sigmoid}(LLR(k)\ell (c{)}_k)\right)\\ & =\sum _{k=0}^{K-1}\log \left(\text{sigmoid}(LLR(k)\ell (c{)}_k)\right)\end{array}\end{array}$$

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(b_i=0|y)}{Pr(b_i=1|y)}\right)$.

class sionna.phy.mapping.PAMSource(num_bits_per_symbol=None, return_indices=False, return_bits=False, seed=None, precision=None, **kwargs)

Generates a tensor of random PAM symbols

Optionally, the symbol indices and/or binary representations of the constellation symbols can be returned.

Parameters:

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

• return_indices (bool, (default False)) – If enabled, the function also returns the symbol indices.

• return_bits (bool, (default False)) – If enabled, the function also returns the binary symbol representations (i.e., bit labels). Defaults to False.

• seed (None (default) | int) – Set the seed for the random generator used to generate the bits. If set to None, tf_rng is used.

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs. If set to None, precision is used.

Input:

shape (1D tensor/array/list, int) – Desired shape of the output tensor

Output:

• symbols (shape, tf.complex) – Tensor filled with random PAM symbols

• symbol_indices (shape, tf.int32) – Tensor filled with the symbol indices. Only returned if return_indices is True.

• bits ([shape, num_bits_per_symbol], tf.float) – Tensor filled with the binary symbol representations (i.e., bit labels). Only returned if return_bits is True.

class sionna.phy.mapping.PAM2QAM(num_bits_per_symbol, hard_in_out=True, precision=None, **kwargs)

Transforms PAM symbol indices/logits to QAM symbol indices/logits

For two PAM constellation symbol indices or logits, corresponding to the real and imaginary components of a QAM constellation, compute the QAM symbol index or logits.

Parameters:

• num_bits_per_symbol (int) – Number of bits per QAM constellation symbol, e.g., 4 for QAM16

• hard_in_out (bool, (default True)) – Determines if inputs and outputs are indices or logits over constellation symbols.

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs. If set to None, precision is used.

Input:

• pam1 (Tensor, tf.int32, or […,2**(num_bits_per_symbol/2)], tf.float) – Indices or logits for the first PAM constellation

• pam2 (Tensor, tf.int32, or […,2**(num_bits_per_symbol/2)], tf.float) – Indices or logits for the second PAM constellation

Output:

qam (Tensor, tf.int32, or […,2**num_bits_per_symbol], tf.float) – Indices or logits for the corresponding QAM constellation

class sionna.phy.mapping.QAMSource(num_bits_per_symbol=None, return_indices=False, return_bits=False, seed=None, precision=None, **kwargs)

Generates a tensor of random QAM symbols

Optionally, the symbol indices and/or binary representations of the constellation symbols can be returned.

Parameters:

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

• return_indices (bool, (default False)) – If enabled, the function also returns the symbol indices.

• return_bits (bool, (default False)) – If enabled, the function also returns the binary symbol representations (i.e., bit labels).

• seed (None (default) | int) – Set the seed for the random generator used to generate the bits. If set to None, tf_rng is used.

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs. If set to None, precision is used.

Input:

shape (1D tensor/array/list, int) – Desired shape of the output tensor

Output:

• symbols (shape, tf.complex) – Tensor filled with random QAM symbols

• symbol_indices (shape, tf.int32) – Tensor filled with the symbol indices. Only returned if return_indices is True.

• bits ([shape, num_bits_per_symbol], tf.float) – Tensor filled with the binary symbol representations (i.e., bit labels). Only returned if return_bits is True.

class sionna.phy.mapping.QAM2PAM(num_bits_per_symbol, precision=None, **kwargs)

Transforms QAM symbol indices to PAM symbol indices

For indices in a QAM constellation, computes the corresponding indices for the two PAM constellations corresponding the real and imaginary components of the QAM constellation.

Parameters:

• num_bits_per_symbol (int) – Number of bits per QAM constellation symbol, e.g., 4 for QAM16.

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs. If set to None, precision is used.

Input:

ind_qam (Tensor, tf.int32) – Indices in the QAM constellation

Output:

• ind_pam1 (Tensor, tf.int32) – Indices for the first component of the corresponding PAM modulation

• ind_pam2 (Tensor, tf.int32) – Indices for the first component of the corresponding PAM modulation

class sionna.phy.mapping.SymbolInds2Bits(num_bits_per_symbol, precision=None, **kwargs)

Transforms symbol indices to their binary representations

Parameters:

• num_bits_per_symbol (int) – Number of bits per constellation symbol

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs. If set to None, precision is used.

Input:

Tensor, tf.int – Symbol indices

Output:

input.shape + [num_bits_per_symbol], tf.float – Binary representation of symbol indices

class sionna.phy.mapping.SymbolLogits2LLRs(method, num_bits_per_symbol, *, hard_out=False, precision=None, **kwargs)

Computes log-likelihood ratios (LLRs) or hard-decisions on bits from a tensor of logits (i.e., unnormalized log-probabilities) on constellation points. Prior knowledge on the bits can be optionally provided

Parameters:

• method ("app" | "maxlog") – Method used for computing the LLRs

• num_bits_per_symbol (int) – Number of bits per constellation symbol, e.g., 4 for QAM16.

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

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs. If set to None, precision is used.

Input:

• logits ([…,n, num_points], tf.float) – Logits on constellation points

• prior (None (default) | [num_bits_per_symbol] or […n, num_bits_per_symbol], tf.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].

Output:

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

Note

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

$$LLR(i)=\ln \left(\frac{Pr(b_i=1|\mathbf{z},\mathbf{p})}{Pr(b_i=0|\mathbf{z},\mathbf{p})}\right)=\ln \left(\frac{\sum _{c\in {\mathcal{C}}_{i,1}}Pr(c|\mathbf{p})e^{z_c}}{\sum _{c\in {\mathcal{C}}_{i,0}}Pr(c|\mathbf{p})e^{z_c}}\right)$$

where ${\mathcal{C}}_{i,1}$ and ${\mathcal{C}}_{i,0}$ are the sets of $2^K$ constellation points for which the $i\text{th}$ bit is equal to 1 and 0, respectively. $\mathbf{z}=[z_{c_0},\dots ,z_{c_{2^K-1}}]$ is the vector of logits on the constellation points, $\mathbf{p}=[p_0,\dots ,p_{K-1}]$ 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|\mathbf{p})$ is the prior probability on the constellation symbol $c$:

$$Pr(c|\mathbf{p})=\prod _{k=0}^{K-1}Pr(b_k=\ell (c{)}_k|\mathbf{p})=\prod _{k=0}^{K-1}\text{sigmoid}(p_k\ell (c{)}_k)$$

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(b_i=0|y)}{Pr(b_i=1|y)}\right)$.

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

$$\begin{array}{rl}LLR(i)& \approx \ln \left(\frac{\underset{c\in {\mathcal{C}}_{i,1}}{max}Pr(c|\mathbf{p})e^{z_c}}{\underset{c\in {\mathcal{C}}_{i,0}}{max}Pr(c|\mathbf{p})e^{z_c}}\right).\end{array}$$

property num_bits_per_symbol

Number of bits per symbol

Type:

int

class sionna.phy.mapping.SymbolLogits2Moments(constellation_type=None, num_bits_per_symbol=None, constellation=None, precision=None, **kwargs)

Computes the mean and variance of a constellation from logits (unnormalized log-probabilities) on the constellation points

More precisely, given a constellation $\mathcal{C}=[c_0,\dots ,c_{N-1}]$ of size $N$, this layer computes the mean and variance according to

$$\begin{array}{r}\begin{array}{rl}\mu & =\sum _{n=0}^{N-1}{c}_{n}Pr(c_n|\ell )\\ \nu & =\sum _{n=0}^{N-1}{(c_n-\mu )}^{2}Pr(c_n|\ell )\end{array}\end{array}$$

where $\ell =[{\ell }_0,\dots ,{\ell }_{N-1}]$ are the logits, and

$$Pr(c_n|\ell )=\frac{\exp \left({\ell }_n\right)}{\sum _{i=0}^{N-1}\exp \left({\ell }_i\right)}.$$

Parameters:

• constellation_type ("qam" | "pam" | "custom") – For “custom”, an instance of Constellation must be provided.

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

• constellation (None (default) | Constellation) – If no constellation is provided, constellation_type and num_bits_per_symbol must be provided.

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs. If set to None, precision is used.

Input:

logits ([…,n, num_points], tf.float) – Logits on constellation points

Output:

• mean ([…,n], tf.float) – Mean of the constellation

• var ([…,n], tf.float) – Variance of the constellation

class sionna.phy.mapping.SymbolSource(constellation_type=None, num_bits_per_symbol=None, constellation=None, return_indices=False, return_bits=False, seed=None, precision=None, **kwargs)

Generates a tensor of random constellation symbols

Optionally, the symbol indices and/or binary representations of the constellation symbols can be returned.

Parameters:

• constellation_type (str, “qam” | “pam” | “custom”]) – For “custom”, an instance of Constellation must be provided.

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

• constellation (None (default) | Constellation) – If no constellation is provided, constellation_type and num_bits_per_symbol must be provided.

• return_indices (bool, (default False)) – If enabled, the function also returns the symbol indices.

• return_bits (bool, (default False)) – If enabled, the function also returns the binary symbol representations (i.e., bit labels).

• seed (None (default) | int) – Set the seed for the random generator used to generate the bits. If set to None, tf_rng is used.

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs. If set to None, precision is used.

Input:

shape (1D tensor/array/list, int) – Desired shape of the output tensor

Output:

• symbols (shape, tf.complex) – Tensor filled with random symbols of the chosen constellation_type.

• symbol_indices (shape, tf.int32) – Tensor filled with the symbol indices. Only returned if return_indices is True.

• bits ([shape, num_bits_per_symbol], tf.float) – Tensor filled with the binary symbol representations (i.e., bit labels). Only returned if return_bits is True.