Utility Functions

classsionna.phy.mapping.BinarySource(precision=None,seed=None,**kwargs)[source]

Generates a random binary tensor

Parameters:

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

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs.If set toNone,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

classsionna.phy.mapping.LLRs2SymbolLogits(num_bits_per_symbol,hard_out=False,precision=None,**kwargs)[source]

Computes logits (i.e., unnormalized log-probabilities) or hard decisionson 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, (defaultFalse)) – IfTrue, 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 toNone,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\) pointis computed according to

\[\begin{split}\begin{align} \log{\left(\Pr\left(c\lvert LLRs \right)\right)} &= \log{\left(\prod_{k=0}^{K-1} \Pr\left(b_k = \ell(c)_k \lvert LLRs \right)\right)}\\ &= \log{\left(\prod_{k=0}^{K-1} \text{sigmoid}\left(LLR(k) \ell(c)_k\right)\right)}\\ &= \sum_{k=0}^{K-1} \log{\left(\text{sigmoid}\left(LLR(k) \ell(c)_k\right)\right)}\end{align}\end{split}\]

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

classsionna.phy.mapping.PAMSource(num_bits_per_symbol=None,return_indices=False,return_bits=False,seed=None,precision=None,**kwargs)[source]

Generates a tensor of random PAM symbols

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

Parameters:

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

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

• return_bits (bool, (defaultFalse)) – If enabled, the function also returns the binary symbolrepresentations (i.e., bit labels).Defaults toFalse.

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

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs.If set toNone,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 ifreturn_indices isTrue.

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

classsionna.phy.mapping.PAM2QAM(num_bits_per_symbol,hard_in_out=True,precision=None,**kwargs)[source]

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

For two PAM constellation symbol indices or logits, corresponding tothe 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, (defaultTrue)) – Determines if inputs and outputs are indices or logits overconstellation symbols.

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs.If set toNone,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

classsionna.phy.mapping.QAMSource(num_bits_per_symbol=None,return_indices=False,return_bits=False,seed=None,precision=None,**kwargs)[source]

Generates a tensor of random QAM symbols

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

Parameters:

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

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

• return_bits (bool, (defaultFalse)) – If enabled, the function also returns the binary symbolrepresentations (i.e., bit labels).

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

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs.If set toNone,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 ifreturn_indices isTrue.

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

classsionna.phy.mapping.QAM2PAM(num_bits_per_symbol,precision=None,**kwargs)[source]

Transforms QAM symbol indices to PAM symbol indices

For indices in a QAM constellation, computes the corresponding indicesfor the two PAM constellations corresponding the real and imaginarycomponents 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 toNone,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

classsionna.phy.mapping.SymbolInds2Bits(num_bits_per_symbol,precision=None,**kwargs)[source]

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 toNone,precision is used.

Input:

Tensor,tf.int – Symbol indices

Output:

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

classsionna.phy.mapping.SymbolLogits2LLRs(method,num_bits_per_symbol,*,hard_out=False,precision=None,**kwargs)[source]

Computes log-likelihood ratios (LLRs) or hard-decisions on bitsfrom 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, (defaultFalse)) – IfTrue, the layer provides hard-decided bits instead of soft-values.

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs.If set toNone,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}\) bitis computed according to

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

where\(\mathcal{C}_{i,1}\) and\(\mathcal{C}_{i,0}\) are thesets of\(2^K\) constellation points for which the\(i\text{th}\) bit isequal to 1 and 0, respectively.\(\mathbf{z} = \left[z_{c_0},\dots,z_{c_{2^K-1}}\right]\) is the vector of logits on the constellation points,\(\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 toa 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} \Pr\left(b_k = \ell(c)_k \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 isreplaced by -1.The definition of the LLR has beenchosen such that it is equivalent with that of logits. This isdifferent from many textbooks in communications, where the LLR isdefined 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” method, LLRs for the\(i\text{th}\) bitare approximated like

\[\begin{align} LLR(i) &\approx\ln\left(\frac{ \max_{c\in\mathcal{C}_{i,1}} \Pr\left(c\lvert\mathbf{p}\right) e^{z_c} }{ \max_{c\in\mathcal{C}_{i,0}} \Pr\left(c\lvert\mathbf{p}\right) e^{z_c} }\right) .\end{align}\]

propertynum_bits_per_symbol

Number of bits per symbol

Type:

int

classsionna.phy.mapping.SymbolLogits2Moments(constellation_type=None,num_bits_per_symbol=None,constellation=None,precision=None,**kwargs)[source]

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

More precisely, given a constellation\(\mathcal{C} = \left[ c_0,\dots,c_{N-1} \right]\) of size\(N\), this layer computes the mean and varianceaccording to

\[\begin{split}\begin{align} \mu &= \sum_{n = 0}^{N-1} c_n \Pr \left(c_n \lvert \mathbf{\ell} \right)\\ \nu &= \sum_{n = 0}^{N-1} \left( c_n - \mu \right)^2 \Pr \left(c_n \lvert \mathbf{\ell} \right)\end{align}\end{split}\]

where\(\mathbf{\ell} = \left[ \ell_0, \dots, \ell_{N-1} \right]\) are the logits, and

\[\Pr \left(c_n \lvert \mathbf{\ell} \right) = \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 ofConstellationmust be provided.

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

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

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs.If set toNone,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

classsionna.phy.mapping.SymbolSource(constellation_type=None,num_bits_per_symbol=None,constellation=None,return_indices=False,return_bits=False,seed=None,precision=None,**kwargs)[source]

Generates a tensor of random constellation symbols

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

Parameters:

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

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

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

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

• return_bits (bool, (defaultFalse)) – If enabled, the function also returns the binary symbolrepresentations (i.e., bit labels).

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

• precision (None (default) | “single” | “double”) – Precision used for internal calculations and outputs.If set toNone,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 chosenconstellation_type.

• symbol_indices (shape,tf.int32) – Tensor filled with the symbol indices.Only returned ifreturn_indices isTrue.

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