Multiple-Input Multiple-Output (MIMO)

Stream Management

Stream management determines which transmitter is sending which stream to which receiver. Transmitters and receivers can be user terminals or base stations, depending on whether uplink or downlink transmissions are considered. The StreamManagement class has various properties that are needed to recover desired or interfering channel coefficients for precoding and equalization. In order to understand how the various properties of StreamManagement can be used, we recommend to have a look at the source code of the LMMSEEqualizer or RZFPrecoder.

The following code snippet shows how to configure StreamManagement for a simple uplink scenario, where four transmitters send each one stream to a receiver. Note that StreamManagement is independent of the actual number of antennas at the transmitters and receivers.

num_tx = 4
num_rx = 1
num_streams_per_tx = 1

# Indicate which transmitter is associated with which receiver
# rx_tx_association[i,j] = 1 means that transmitter j sends one
# or mutiple streams to receiver i.
rx_tx_association = np.zeros([num_rx, num_tx])
rx_tx_association[0,0] = 1
rx_tx_association[0,1] = 1
rx_tx_association[0,2] = 1
rx_tx_association[0,3] = 1

sm = StreamManagement(rx_tx_association, num_streams_per_tx)

class sionna.phy.mimo.StreamManagement(rx_tx_association, num_streams_per_tx)

Class for management of streams in multi-cell MIMO networks.

Parameters:

• rx_tx_association ([num_rx, num_tx], np.int) – A binary NumPy array where rx_tx_association[i,j]=1 means that receiver i gets one or multiple streams from transmitter j.

• num_streams_per_tx (int) – Indicates the number of streams that are transmitted by each transmitter.

Note

Several symmetry constraints on rx_tx_association are imposed to ensure efficient processing. All row sums and all column sums must be equal, i.e., all receivers have the same number of associated transmitters and all transmitters have the same number of associated receivers. It is also assumed that all transmitters send the same number of streams num_streams_per_tx.

property detection_desired_ind

Indices needed to gather desired channels for receive processing

A NumPy array of shape [num_rx*num_streams_per_rx] that can be used to gather desired channels from the flattened channel tensor of shape […,num_rx, num_tx, num_streams_per_tx,…]. The result of the gather operation can be reshaped to […,num_rx, num_streams_per_rx,…].

property detection_undesired_ind

Indices needed to gather undesired channels for receive processing

A NumPy array of shape [num_rx*num_streams_per_rx] that can be used to gather undesired channels from the flattened channel tensor of shape […,num_rx, num_tx, num_streams_per_tx,…]. The result of the gather operation can be reshaped to […,num_rx, num_interfering_streams_per_rx,…].

property num_interfering_streams_per_rx

Number of interfering streams received at each eceiver

property num_rx

Number of receivers

property num_rx_per_tx

Number of receivers communicating with a transmitter

property num_streams_per_rx

Number of streams transmitted to each receiver

property num_streams_per_tx

Number of streams per transmitter

property num_tx

Number of transmitters

property num_tx_per_rx

Number of transmitters communicating with a receiver

property precoding_ind

Indices needed to gather channels for precoding

A NumPy array of shape [num_tx, num_rx_per_tx], where precoding_ind[i,:] contains the indices of the receivers to which transmitter i is sending streams.

property rx_stream_ids

Mapping of streams to receivers

A Numpy array of shape [num_rx, num_streams_per_rx]. This array is obtained from tx_stream_ids together with the rx_tx_association. rx_stream_ids[i,:] contains the indices of streams that are supposed to be decoded by receiver i.

property rx_tx_association

Association between receivers and transmitters.

A binary NumPy array of shape [num_rx, num_tx], where rx_tx_association[i,j]=1 means that receiver i gets one ore multiple streams from transmitter j.

property stream_association

Association between receivers, transmitters, and streams

A binary NumPy array of shape [num_rx, num_tx, num_streams_per_tx], where stream_association[i,j,k]=1 means that receiver i gets the k th stream from transmitter j.

property stream_ind

Indices needed to gather received streams in the correct order

A NumPy array of shape [num_rx*num_streams_per_rx] that can be used to gather streams from the flattened tensor of received streams of shape […,num_rx, num_streams_per_rx,…]. The result of the gather operation is then reshaped to […,num_tx, num_streams_per_tx,…].

property tx_stream_ids

Mapping of streams to transmitters

A NumPy array of shape [num_tx, num_streams_per_tx]. Streams are numbered from 0,1,… and assiged to transmitters in increasing order, i.e., transmitter 0 gets the first num_streams_per_tx and so on.

Precoding

sionna.phy.mimo.cbf_precoding_matrix(h, precision=None)

Computes the conjugate beamforming (CBF) Precoder

This function computes the CBF precoding matrix for a MIMO link, assuming the following model:

$$\mathbf{y}=\mathbf{H}\mathbf{G}\mathbf{x}+\mathbf{n}$$

where $\mathbf{y}\in {\mathbb{C}}^K$ is the received signal vector, $\mathbf{H}\in {\mathbb{C}}^{K\times M}$ is the known channel matrix, $\mathbf{G}\in {\mathbb{C}}^{M\times K}$ is the precoding matrix, $\mathbf{x}\in {\mathbb{C}}^K$ is the symbol vector to be precoded, and $\mathbf{n}\in {\mathbb{C}}^K$ is a noise vector.

The precoding matrix $\mathbf{G}$ is defined as :

$$\mathbf{G}=\mathbf{V}\mathbf{D}$$

where

$$\begin{array}{rl}\mathbf{V}& ={\mathbf{H}}^{\mathsf{H}}\\ \mathbf{D}& =\text{diag}(\Vert {\mathbf{v}}_k{\Vert }_2^{-1},k=0,\dots ,K-1).\end{array}$$

The matrix $\mathbf{V}$ ensures that each stream is precoded with a unit-norm vector, i.e., $\text{tr}\left(\mathbf{G}{\mathbf{G}}^{\mathsf{H}}\right)=K$. The function returns the matrix $\mathbf{G}$.

Input:

• h ([…,K,M], tf.complex) – 2+D tensor containing the channel matrices

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

Output:

g ([…,M,K], tf.complex) – 2+D tensor containing the precoding matrices

sionna.phy.mimo.rzf_precoding_matrix(h, alpha=0.0, precision=None)

Computes the Regularized Zero-Forcing (RZF) Precoder

This function computes the RZF precoding matrix for a MIMO link, assuming the following model:

$$\mathbf{y}=\mathbf{H}\mathbf{G}\mathbf{x}+\mathbf{n}$$

where $\mathbf{y}\in {\mathbb{C}}^K$ is the received signal vector, $\mathbf{H}\in {\mathbb{C}}^{K\times M}$ is the known channel matrix, $\mathbf{G}\in {\mathbb{C}}^{M\times K}$ is the precoding matrix, $\mathbf{x}\in {\mathbb{C}}^K$ is the symbol vector to be precoded, and $\mathbf{n}\in {\mathbb{C}}^K$ is a noise vector.

The precoding matrix $\mathbf{G}$ is defined as :

$$\mathbf{G}=\mathbf{V}\mathbf{D}$$

where

$$\begin{array}{rl}\mathbf{V}& ={\mathbf{H}}^{\mathsf{H}}{(\mathbf{H}{\mathbf{H}}^{\mathsf{H}}+\alpha \mathbf{I})}^{-1}\\ \mathbf{D}& =\text{diag}(\Vert {\mathbf{v}}_k{\Vert }_2^{-1},k=0,\dots ,K-1)\end{array}$$

where $\alpha >0$ is the regularization parameter. The matrix $\mathbf{V}$ ensures that each stream is precoded with a unit-norm vector, i.e., $\text{tr}\left(\mathbf{G}{\mathbf{G}}^{\mathsf{H}}\right)=K$. The function returns the matrix $\mathbf{G}$.

Input:

• h ([…,K,M], tf.complex) – 2+D tensor containing the channel matrices

• alpha (0. (default) | […], tf.float32) – Regularization parameter

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

Output:

g ([…,M,K], tf.complex) – 2+D tensor containing the precoding matrices

sionna.phy.mimo.rzf_precoder(x, h, alpha=0.0, return_precoding_matrix=False, precision=None)

Regularized Zero-Forcing (RZF) Precoder

This function implements RZF precoding for a MIMO link, assuming the following model:

$$\mathbf{y}=\mathbf{H}\mathbf{G}\mathbf{x}+\mathbf{n}$$

where $\mathbf{y}\in {\mathbb{C}}^K$ is the received signal vector, $\mathbf{H}\in {\mathbb{C}}^{K\times M}$ is the known channel matrix, $\mathbf{G}\in {\mathbb{C}}^{M\times K}$ is the precoding matrix, $\mathbf{x}\in {\mathbb{C}}^K$ is the symbol vector to be precoded, and $\mathbf{n}\in {\mathbb{C}}^K$ is a noise vector.

The precoding matrix $\mathbf{G}$ is defined as (Eq. 4.37) [BHS2017] :

$$\mathbf{G}=\mathbf{V}\mathbf{D}$$

where

$$\begin{array}{rl}\mathbf{V}& ={\mathbf{H}}^{\mathsf{H}}{(\mathbf{H}{\mathbf{H}}^{\mathsf{H}}+\alpha \mathbf{I})}^{-1}\\ \mathbf{D}& =\text{diag}(\Vert {\mathbf{v}}_k{\Vert }_2^{-1},k=0,\dots ,K-1)\end{array}$$

where $\alpha >0$ is the regularization parameter.

This ensures that each stream is precoded with a unit-norm vector, i.e., $\text{tr}\left(\mathbf{G}{\mathbf{G}}^{\mathsf{H}}\right)=K$. The function returns the precoded vector $\mathbf{G}\mathbf{x}$.

Input:

• x ([…,K], tf.complex) – Symbol vectors to be precoded

• h ([…,K,M], tf.complex) – Channel matrices

• alpha (0. (default) | […], tf.float32) – Regularization parameter

• return_precoding_matrices (bool, (default, False)) – Indicates if the precoding matrices should be returned or not

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

Output:

• x_precoded ([…,M], tf.complex) – Precoded symbol vectors

• g ([…,M,K], tf.complex) – Precoding matrices. Only returned if return_precoding_matrices=True.

sionna.phy.mimo.grid_of_beams_dft_ula(num_ant, oversmpl=1, precision=None)

Computes the Discrete Fourier Transform (DFT) Grid of Beam (GoB) coefficients for a uniform linear array (ULA)

The coefficient applied to antenna $n$ for beam $m$ is expressed as:

$$c_n^m=e^{\frac{2\pi nm}{NO}},n=0,\dots ,N-1,m=0,\dots ,NO$$

where $N$ is the number of antennas num_ant and $O$ is the oversampling factor oversmpl.

Note that the main lobe of beam $m$ points in the azimuth direction $\theta =\mathrm{arc}\sin \left(2\frac{m}{N}\right)$ if $m\le N/2$ and $\theta =\mathrm{arc}\sin \left(2\frac{m-N}{N}\right)$ if $m\ge N/2$, where $\theta =0$ defines the perpendicular to the antenna array.

Input:

• num_ant (int) – Number of antennas

• oversmpl (int, (default 1)) – Oversampling factor

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

Output:

gob ([num_ant x oversmpl, num_ant], tf.complex) – The $m$-th row contains the num_ant antenna coefficients for the $m$-th DFT beam.

sionna.phy.mimo.grid_of_beams_dft(num_ant_v, num_ant_h, oversmpl_v=1, oversmpl_h=1, precision=None)

Computes the Discrete Fourier Transform (DFT) Grid of Beam (GoB) coefficients for a uniform rectangular array (URA)

GoB indices are arranged over a 2D grid indexed by $(m_v,m_h)$. The coefficient of the beam with index $(m_v,m_h)$ applied to the antenna located at row $n_v$ and column $n_h$ of the rectangular array is expressed as:

$$c_{n_v,n_h}^{m_v,m_h}=e^{\frac{2\pi n_h{m}_v}{N_h{O}_h}}{e}^{\frac{2\pi n_h{m}_h}{N_v{O}_v}}$$

where $n_v=0,\dots ,N_v-1$, $n_h=0,\dots ,N_h-1$, $m_v=0,\dots ,N_v{O}_v$, $m_h=0,\dots ,N_h{O}_h$, $N$ is the number of antennas num_ant and $O_v,O_h$ are the oversampling factor oversmpl_v, oversmpl_h in the vertical and horizontal direction, respectively.

We can rewrite more concisely the matrix coefficients $c^{m_v,m_h}$ as follows:

$$c^{m_v,m_h}=c^{m_v}\otimes c^{m_h}$$

where $\otimes$ denotes the Kronecker product and $c^{m_v},c^{m_h}$ are the ULA DFT beams computed as in grid_of_beams_dft_ula().

Such a DFT GoB is, e.g., defined in Section 5.2.2.2.1 [3GPP38214].

Input:

• num_ant_v (int) – Number of antenna rows (i.e., in vertical direction) of the rectangular array

• num_ant_h (int) – Number of antenna columns (i.e., in horizontal direction) of the rectangular array.

• oversmpl_v (int, (default 1)) – Oversampling factor in vertical direction

• oversmpl_h (int, (default 1)) – Oversampling factor in horizontal direction

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

Output:

gob ([num_ant_v x oversmpl_v, num_ant_h x oversmpl_h, num_ant_v x num_ant_h], tf.complex) – The elements $[m_v,m_h,:]$ contain the antenna coefficients of the DFT beam with index pair $(m_v,m_h)$.

sionna.phy.mimo.flatten_precoding_mat(precoding_mat, by_column=True)

Flattens a […, num_ant_v, num_ant_h] precoding matrix associated with a rectangular array by producing a […, num_ant_v x num_ant_h] precoding vector

Input:

• precoding_mat ([…, num_antennas_vertical, num_antennas_horizontal], tf.complex) – Precoding matrix. The element $(i,j)$ contains the precoding coefficient of the antenna element located at row $i$ and column $j$ of a rectangular antenna array.

• by_column (bool, (default True)) – If True, then flattening occurs on a per-column basis, i.e., the first column is appended to the second, and so on. Else, flattening is performed on a per-row basis.

Output:

[…, num_antennas_vertical x num_antennas_horizontal], tf.complex – Flattened precoding matrix

sionna.phy.mimo.normalize_precoding_power(precoding_vec, tx_power_list=None, precision=None)

Normalizes the beam coefficient power to 1 by default, or to tx_power_list if provided as input

Input:

• precoding_vec ([N,M], tf.complex) – Each row contains a set of antenna coefficients whose power is to be normalized.

• tx_power_list ([N], float) – The $i$-th element defines the power of the $i$-th precoding vector.

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

Output:

[N,M] tf.complex – Normalized antenna coefficients

Equalization

sionna.phy.mimo.lmmse_matrix(h, s=None, precision=None)

MIMO LMMSE Equalization matrix

This function computes the LMMSE equalization matrix for a MIMO link, assuming the following model:

$$\mathbf{y}=\mathbf{H}\mathbf{x}+\mathbf{n}$$

where $\mathbf{y}\in {\mathbb{C}}^M$ is the received signal vector, $\mathbf{x}\in {\mathbb{C}}^K$ is the vector of transmitted symbols, $\mathbf{H}\in {\mathbb{C}}^{M\times K}$ is the known channel matrix, and $\mathbf{n}\in {\mathbb{C}}^M$ is a noise vector. It is assumed that $\mathbb{E}\left[\mathbf{x}\right]=\mathbb{E}\left[\mathbf{n}\right]=\mathbf{0}$, $\mathbb{E}\left[\mathbf{x}{\mathbf{x}}^{\mathsf{H}}\right]={\mathbf{I}}_K$ and $\mathbb{E}\left[\mathbf{n}{\mathbf{n}}^{\mathsf{H}}\right]=\mathbf{S}$.

This function returns the LLMSE equalization matrix:

$$\mathbf{G}={\mathbf{H}}^{\mathsf{H}}{(\mathbf{H}{\mathbf{H}}^{\mathsf{H}}+\mathbf{S})}^{-1}.$$

If $\mathbf{S}={\mathbf{I}}_M$, a numerically more stable version of the equalization matrix is computed:

$$\mathbf{G}={({\mathbf{H}}^{\mathsf{H}}\mathbf{H}+\mathbf{I})}^{-1}{\mathbf{H}}^{\mathsf{H}}.$$

Input:

• h ([…,M,K], tf.complex) – Channel matrices

• s (None (default) | […,M,M], tf.complex) – Noise covariance matrices. If None, the noise is assumed to be white with unit variance.

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

Output:

g ([…,K,M], tf.complex) – LLMSE equalization matrices

sionna.phy.mimo.lmmse_equalizer(y, h, s, whiten_interference=True, precision=None)

MIMO LMMSE Equalizer

This function implements LMMSE equalization for a MIMO link, assuming the following model:

$$\mathbf{y}=\mathbf{H}\mathbf{x}+\mathbf{n}$$

where $\mathbf{y}\in {\mathbb{C}}^M$ is the received signal vector, $\mathbf{x}\in {\mathbb{C}}^K$ is the vector of transmitted symbols, $\mathbf{H}\in {\mathbb{C}}^{M\times K}$ is the known channel matrix, and $\mathbf{n}\in {\mathbb{C}}^M$ is a noise vector. It is assumed that $\mathbb{E}\left[\mathbf{x}\right]=\mathbb{E}\left[\mathbf{n}\right]=\mathbf{0}$, $\mathbb{E}\left[\mathbf{x}{\mathbf{x}}^{\mathsf{H}}\right]={\mathbf{I}}_K$ and $\mathbb{E}\left[\mathbf{n}{\mathbf{n}}^{\mathsf{H}}\right]=\mathbf{S}$.

The estimated symbol vector $\hat{\mathbf{x}}\in {\mathbb{C}}^K$ is given as (Lemma B.19) [BHS2017] :

$$\hat{\mathbf{x}}=\text{diag}{\left(\mathbf{G}\mathbf{H}\right)}^{-1}\mathbf{G}\mathbf{y}$$

where

$$\mathbf{G}={\mathbf{H}}^{\mathsf{H}}{(\mathbf{H}{\mathbf{H}}^{\mathsf{H}}+\mathbf{S})}^{-1}.$$

This leads to the post-equalized per-symbol model:

$${\hat{x}}_k=x_k+e_k,k=0,\dots ,K-1$$

where the variances ${\sigma }_k^2$ of the effective residual noise terms $e_k$ are given by the diagonal elements of

$$\text{diag}\left(\mathbb{E}\left[\mathbf{e}{\mathbf{e}}^{\mathsf{H}}\right]\right)=\text{diag}{\left(\mathbf{G}\mathbf{H}\right)}^{-1}-\mathbf{I}.$$

Note that the scaling by $\text{diag}{\left(\mathbf{G}\mathbf{H}\right)}^{-1}$ is important for the Demapper although it does not change the signal-to-noise ratio.

The function returns $\hat{\mathbf{x}}$ and ${\mathit{\sigma }}^2={[{\sigma }_0^2,\dots ,{\sigma }_{K-1}^2]}^{\mathsf{T}}$.

Input:

• y ([…,M], tf.complex) – Received signals

• h ([…,M,K], tf.complex) – Channel matrices

• s ([…,M,M], tf.complex) – Noise covariance matrices

• whiten_interference (bool, (default True)) – If True, the interference is first whitened before equalization. In this case, an alternative expression for the receive filter is used that can be numerically more stable.

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

Output:

• x_hat ([…,K], tf.complex) – Estimated symbol vectors

• no_eff (tf.float) – Effective noise variance estimates

sionna.phy.mimo.mf_equalizer(y, h, s, precision=None)

MIMO Matched Filter (MF) Equalizer

This function implements matched filter (MF) equalization for a MIMO link, assuming the following model:

$$\mathbf{y}=\mathbf{H}\mathbf{x}+\mathbf{n}$$

where $\mathbf{y}\in {\mathbb{C}}^M$ is the received signal vector, $\mathbf{x}\in {\mathbb{C}}^K$ is the vector of transmitted symbols, $\mathbf{H}\in {\mathbb{C}}^{M\times K}$ is the known channel matrix, and $\mathbf{n}\in {\mathbb{C}}^M$ is a noise vector. It is assumed that $\mathbb{E}\left[\mathbf{x}\right]=\mathbb{E}\left[\mathbf{n}\right]=\mathbf{0}$, $\mathbb{E}\left[\mathbf{x}{\mathbf{x}}^{\mathsf{H}}\right]={\mathbf{I}}_K$ and $\mathbb{E}\left[\mathbf{n}{\mathbf{n}}^{\mathsf{H}}\right]=\mathbf{S}$.

The estimated symbol vector $\hat{\mathbf{x}}\in {\mathbb{C}}^K$ is given as (Eq. 4.11) [BHS2017] :

$$\hat{\mathbf{x}}=\mathbf{G}\mathbf{y}$$

where

$$\mathbf{G}=\text{diag}{\left({\mathbf{H}}^{\mathsf{H}}\mathbf{H}\right)}^{-1}{\mathbf{H}}^{\mathsf{H}}.$$

This leads to the post-equalized per-symbol model:

$${\hat{x}}_k=x_k+e_k,k=0,\dots ,K-1$$

where the variances ${\sigma }_k^2$ of the effective residual noise terms $e_k$ are given by the diagonal elements of the matrix

$$\mathbb{E}\left[\mathbf{e}{\mathbf{e}}^{\mathsf{H}}\right]=(\mathbf{I}-\mathbf{G}\mathbf{H}){(\mathbf{I}-\mathbf{G}\mathbf{H})}^{\mathsf{H}}+\mathbf{G}\mathbf{S}{\mathbf{G}}^{\mathsf{H}}.$$

Note that the scaling by $\text{diag}{\left({\mathbf{H}}^{\mathsf{H}}\mathbf{H}\right)}^{-1}$ in the definition of $\mathbf{G}$ is important for the Demapper although it does not change the signal-to-noise ratio.

The function returns $\hat{\mathbf{x}}$ and ${\mathit{\sigma }}^2={[{\sigma }_0^2,\dots ,{\sigma }_{K-1}^2]}^{\mathsf{T}}$.

Input:

• y ([…,M], tf.complex) – Received signals

• h ([…,M,K], tf.complex) – Channel matrices

• s ([…,M,M], tf.complex) – Noise covariance matrices

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

Output:

• x_hat ([…,K], tf.complex) – Estimated symbol vectors

• no_eff (tf.float) – Effective noise variance estimates

sionna.phy.mimo.zf_equalizer(y, h, s, precision=None)

Applies MIMO ZF Equalizer

This function implements zero-forcing (ZF) equalization for a MIMO link, assuming the following model:

$$\mathbf{y}=\mathbf{H}\mathbf{x}+\mathbf{n}$$

where $\mathbf{y}\in {\mathbb{C}}^M$ is the received signal vector, $\mathbf{x}\in {\mathbb{C}}^K$ is the vector of transmitted symbols, $\mathbf{H}\in {\mathbb{C}}^{M\times K}$ is the known channel matrix, and $\mathbf{n}\in {\mathbb{C}}^M$ is a noise vector. It is assumed that $\mathbb{E}\left[\mathbf{x}\right]=\mathbb{E}\left[\mathbf{n}\right]=\mathbf{0}$, $\mathbb{E}\left[\mathbf{x}{\mathbf{x}}^{\mathsf{H}}\right]={\mathbf{I}}_K$ and $\mathbb{E}\left[\mathbf{n}{\mathbf{n}}^{\mathsf{H}}\right]=\mathbf{S}$.

The estimated symbol vector $\hat{\mathbf{x}}\in {\mathbb{C}}^K$ is given as (Eq. 4.10) [BHS2017] :

$$\hat{\mathbf{x}}=\mathbf{G}\mathbf{y}$$

where

$$\mathbf{G}={\left({\mathbf{H}}^{\mathsf{H}}\mathbf{H}\right)}^{-1}{\mathbf{H}}^{\mathsf{H}}.$$

This leads to the post-equalized per-symbol model:

$${\hat{x}}_k=x_k+e_k,k=0,\dots ,K-1$$

where the variances ${\sigma }_k^2$ of the effective residual noise terms $e_k$ are given by the diagonal elements of the matrix

$$\mathbb{E}\left[\mathbf{e}{\mathbf{e}}^{\mathsf{H}}\right]=\mathbf{G}\mathbf{S}{\mathbf{G}}^{\mathsf{H}}.$$

The function returns $\hat{\mathbf{x}}$ and ${\mathit{\sigma }}^2={[{\sigma }_0^2,\dots ,{\sigma }_{K-1}^2]}^{\mathsf{T}}$.

Input:

• y ([…,M], tf.complex) – Received signals

• h ([…,M,K], tf.complex) – Channel matrices

• s ([…,M,M], tf.complex) – Noise covariance matrices

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

Output:

• x_hat ([…,K], tf.complex) – Estimated symbol vectors

• no_eff (tf.float) – Effective noise variance estimates

Detection

class sionna.phy.mimo.EPDetector(output, num_bits_per_symbol, hard_out=False, l=10, beta=0.9, precision=None, **kwargs)

MIMO Expectation Propagation (EP) detector

This block implements Expectation Propagation (EP) MIMO detection as described in [EP2014]. It can generate hard- or soft-decisions for symbols or bits.

This block assumes the following channel model:

$$\mathbf{y}=\mathbf{H}\mathbf{x}+\mathbf{n}$$

where $\mathbf{y}\in {\mathbb{C}}^M$ is the received signal vector, $\mathbf{x}\in {\mathcal{C}}^S$ is the vector of transmitted symbols which are uniformly and independently drawn from the constellation $\mathcal{C}$, $\mathbf{H}\in {\mathbb{C}}^{M\times S}$ is the known channel matrix, and $\mathbf{n}\in {\mathbb{C}}^M$ is a complex Gaussian noise vector. It is assumed that $\mathbb{E}\left[\mathbf{n}\right]=\mathbf{0}$ and $\mathbb{E}\left[\mathbf{n}{\mathbf{n}}^{\mathsf{H}}\right]=\mathbf{S}$, where $\mathbf{S}$ has full rank.

The channel model is first whitened using whiten_channel() and then converted to its real-valued equivalent, see complex2real_channel(), prior to MIMO detection.

The computation of LLRs is done by converting the symbol logits that naturally arise in the algorithm to LLRs using PAM2QAM(). Custom conversions of symbol logits to LLRs can be implemented by using the soft-symbol output.

The detector is currently restricted to QAM constellations.

Parameters:

• output ("bit" | "symbol") – Type of output, either LLRs on bits or logits on constellation symbols

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

• hard_out (bool, (default False)) – If True, the detector computes hard-decided bit values or constellation point indices instead of soft-values.

• l (int, (default 10)) – Number of iterations

• beta (float, (default 0.9)) – Parameter $\beta \in [0,1]$ for update smoothing

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

Input:

• y ([…,M], tf.complex) – Received signals

• h ([…,M,num_streams], tf.complex) – Channel matrices

• s ([…,M,M], tf.complex) – Noise covariance matrices

Output:

• One of

• […, num_streams, num_bits_per_symbol], tf.float – LLRs or hard-decisions for every bit of every stream, if output equals “bit”.

• […, num_streams, num_points], tf.float or […, num_streams], tf.int32 – Logits or hard-decisions for constellation symbols for every stream, if output equals “symbol”. Hard-decisions correspond to the symbol indices.

class sionna.phy.mimo.KBestDetector(output, num_streams, k, constellation_type=None, num_bits_per_symbol=None, constellation=None, hard_out=False, use_real_rep=False, list2llr=None, precision=None, **kwargs)

MIMO K-Best detector

This block implements K-Best MIMO detection as described in (Eq. 4-5) [FT2015]. It can either generate hard decisions (for symbols or bits) or compute LLRs.

The algorithm operates in either the complex or real-valued domain. Although both options produce identical results, the former has the advantage that it can be applied to arbitrary non-QAM constellations. It also reduces the number of streams (or depth) by a factor of two.

The way soft-outputs (i.e., LLRs) are computed is determined by the list2llr function. The default solution List2LLRSimple assigns a predetermined value to all LLRs without counter-hypothesis.

This block assumes the following channel model:

$$\mathbf{y}=\mathbf{H}\mathbf{x}+\mathbf{n}$$

where $\mathbf{y}\in {\mathbb{C}}^M$ is the received signal vector, $\mathbf{x}\in {\mathcal{C}}^S$ is the vector of transmitted symbols which are uniformly and independently drawn from the constellation $\mathcal{C}$, $\mathbf{H}\in {\mathbb{C}}^{M\times S}$ is the known channel matrix, and $\mathbf{n}\in {\mathbb{C}}^M$ is a complex Gaussian noise vector. It is assumed that $\mathbb{E}\left[\mathbf{n}\right]=\mathbf{0}$ and $\mathbb{E}\left[\mathbf{n}{\mathbf{n}}^{\mathsf{H}}\right]=\mathbf{S}$, where $\mathbf{S}$ has full rank.

In a first optional step, the channel model is converted to its real-valued equivalent, see complex2real_channel(). We assume in the sequel the complex-valued representation. Then, the channel is whitened using whiten_channel():

$$\begin{array}{rl}\tilde{\mathbf{y}}& ={\mathbf{S}}^{-\frac{1}{2}}\mathbf{y}\\ & ={\mathbf{S}}^{-\frac{1}{2}}\mathbf{H}\mathbf{x}+{\mathbf{S}}^{-\frac{1}{2}}\mathbf{n}\\ & =\tilde{\mathbf{H}}\mathbf{x}+\tilde{\mathbf{n}}.\end{array}$$

Next, the columns of $\tilde{\mathbf{H}}$ are sorted according to their norm in descending order. Then, the QR decomposition of the resulting channel matrix is computed:

$$\tilde{\mathbf{H}}=\mathbf{Q}\mathbf{R}$$

where $\mathbf{Q}\in {\mathbb{C}}^{M\times S}$ is unitary and $\mathbf{R}\in {\mathbb{C}}^{S\times S}$ is upper-triangular. The channel outputs are then pre-multiplied by ${\mathbf{Q}}^{\mathsf{H}}$. This leads to the final channel model on which the K-Best detection algorithm operates:

$$\overline{\mathbf{y}}=\mathbf{R}\overline{\mathbf{x}}+\overline{\mathbf{n}}$$

where $\overline{\mathbf{y}}\in {\mathbb{C}}^S$, $\overline{\mathbf{x}}\in {\mathbb{C}}^S$, and $\overline{\mathbf{n}}\in {\mathbb{C}}^S$ with $\mathbb{E}\left[\overline{\mathbf{n}}\right]=\mathbf{0}$ and $\mathbb{E}\left[\overline{\mathbf{n}}{\overline{\mathbf{n}}}^{\mathsf{H}}\right]=\mathbf{I}$.

LLR Computation

The K-Best algorithm produces $K$ candidate solutions ${\overline{\mathbf{x}}}_k\in {\mathcal{C}}^S$ and their associated distance metrics $d_k=\Vert \overline{\mathbf{y}}-\mathbf{R}{\overline{\mathbf{x}}}_k{\Vert }^2$ for $k=1,\dots ,K$. If the real-valued channel representation is used, the distance metrics are scaled by 0.5 to account for the reduced noise power in each complex dimension. A hard-decision is simply the candidate with the shortest distance. Various ways to compute LLRs from this list (and possibly additional side-information) are possible. The (sub-optimal) default solution is List2LLRSimple. Custom solutions can be provided.

Parameters:

• output ("bit" | "symbol") – Type of output, either LLRs on bits or logits on constellation symbols

• num_streams (int) – Number of transmitted streams

• k (int`) – Number of paths to keep. Cannot be larger than the number of constellation points to the power of the number of streams.

• 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 None, constellation_type and num_bits_per_symbol must be provided.

• hard_out (bool, (default False)) – If True, the detector computes hard-decided bit values or constellation point indices instead of soft-values.

• use_real_rep (bool, (default False)) – If True, the detector use the real-valued equivalent representation of the channel. Note that this only works with a QAM constellation.

• list2llr (None (default) | List2LLR) – The function to be used to compute LLRs from a list of candidate solutions. If None, the default solution List2LLRSimple is used.

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

Input:

• y ([…,M], tf.complex) – Received signals

• h ([…,M,num_streams], tf.complex) – Channel matrices

• s ([…,M,M], tf.complex) – Noise covariance matrices

Output:

• One of

• […, num_streams, num_bits_per_symbol], tf.float – LLRs or hard-decisions for every bit of every stream, if output equals “bit”.

• […, num_streams, num_points], tf.float or […, num_streams], tf.int32 – Logits or hard-decisions for constellation symbols for every stream, if output equals “symbol”. Hard-decisions correspond to the symbol indices.

property list2llr

Set/get the function to be used to compute LLRs from a list of candidate solutions

Type:

List2LLR

class sionna.phy.mimo.LinearDetector(equalizer, output, demapping_method, constellation_type=None, num_bits_per_symbol=None, constellation=None, hard_out=False, precision=None, **kwargs)

Convenience class that combines an equalizer, such as lmmse_equalizer(), and a Demapper.

Parameters:

• equalizer ("lmmse" | "zf" | "mf" | equalizer function) – The equalizer to be used. Either one of the existing equalizers lmmse_equalizer(), zf_equalizer(), or mf_equalizer() can be used, or a custom equalizer callable provided that has the same input/output specification.

• output ("bit" | "symbol") – Type of output, either LLRs on bits or logits on constellation symbols

• demapping_method ("app" | "maxlog") – Demapping method to be used

• 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 None, constellation_type and num_bits_per_symbol must be provided.

• hard_out (bool, (default False)) – If True, the detector computes hard-decided bit values or constellation point indices 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 ([…,M], tf.complex) – Received signals

• h ([…,M,num_streams], tf.complex) – Channel matrices

• s ([…,M,M], tf.complex) – Noise covariance matrices

Output:

• One of

• […, num_streams, num_bits_per_symbol], tf.float – LLRs or hard-decisions for every bit of every stream, if output equals “bit”

• […, num_streams, num_points], tf.float or […, num_streams], tf.int32 – Logits or hard-decisions for constellation symbols for every stream, if output equals “symbol” Hard-decisions correspond to the symbol indices.

class sionna.phy.mimo.MaximumLikelihoodDetector(output, demapping_method, num_streams, constellation_type=None, num_bits_per_symbol=None, constellation=None, hard_out=False, precision=None, **kwargs)

MIMO maximum-likelihood (ML) detector

This block implements MIMO maximum-likelihood (ML) detection assuming the following channel model:

$$\mathbf{y}=\mathbf{H}\mathbf{x}+\mathbf{n}$$

where $\mathbf{y}\in {\mathbb{C}}^M$ is the received signal vector, $\mathbf{x}\in {\mathcal{C}}^K$ is the vector of transmitted symbols which are uniformly and independently drawn from the constellation $\mathcal{C}$, $\mathbf{H}\in {\mathbb{C}}^{M\times K}$ is the known channel matrix, and $\mathbf{n}\in {\mathbb{C}}^M$ is a complex Gaussian noise vector. It is assumed that $\mathbb{E}\left[\mathbf{n}\right]=\mathbf{0}$ and $\mathbb{E}\left[\mathbf{n}{\mathbf{n}}^{\mathsf{H}}\right]=\mathbf{S}$, where $\mathbf{S}$ has full rank. Optionally, prior information of the transmitted signal $\mathbf{x}$ can be provided, either as LLRs on the bits mapped onto $\mathbf{x}$ or as logits on the individual constellation points forming $\mathbf{x}$.

Prior to demapping, the received signal is whitened:

$$\begin{array}{rl}\tilde{\mathbf{y}}& ={\mathbf{S}}^{-\frac{1}{2}}\mathbf{y}\\ & ={\mathbf{S}}^{-\frac{1}{2}}\mathbf{H}\mathbf{x}+{\mathbf{S}}^{-\frac{1}{2}}\mathbf{n}\\ & =\tilde{\mathbf{H}}\mathbf{x}+\tilde{\mathbf{n}}\end{array}$$

The block can compute ML detection of symbols or bits with either soft- or hard-decisions. Note that decisions are computed symbol-/bit-wise and not jointly for the entire vector $\mathbf{\text{x}}$ (or the underlying vector of bits).

ML detection of bits:

Soft-decisions on bits are called log-likelihood ratios (LLR). With the “app” demapping method, the LLR for the $i\text{th}$ bit of the $k\text{th}$ user is then computed according to

$$\begin{array}{r}\begin{array}{rl}LLR(k,i)& =\ln \left(\frac{Pr(b_{k,i}=1|\mathbf{y},\mathbf{H})}{Pr(b_{k,i}=0|\mathbf{y},\mathbf{H})}\right)\\ & =\ln \left(\frac{\sum _{\mathbf{x}\in {\mathcal{C}}_{k,i,1}}\exp (-{\Vert \tilde{\mathbf{y}}-\tilde{\mathbf{H}}\mathbf{x}\Vert }^2)Pr\left(\mathbf{x}\right)}{\sum _{\mathbf{x}\in {\mathcal{C}}_{k,i,0}}\exp (-{\Vert \tilde{\mathbf{y}}-\tilde{\mathbf{H}}\mathbf{x}\Vert }^2)Pr\left(\mathbf{x}\right)}\right)\end{array}\end{array}$$

where ${\mathcal{C}}_{k,i,1}$ and ${\mathcal{C}}_{k,i,0}$ are the sets of vectors of constellation points for which the $i\text{th}$ bit of the $k\text{th}$ user is equal to 1 and 0, respectively. $Pr\left(\mathbf{x}\right)$ is the prior distribution of the vector of constellation points $\mathbf{x}$. Assuming that the constellation points and bit levels are independent, it is computed from the prior of the bits according to

$$Pr\left(\mathbf{x}\right)=\prod _{k=1}^K\prod _{i=1}^I\sigma (LL{R}_p(k,i))$$

where $LL{R}_p(k,i)$ is the prior knowledge of the $i\text{th}$ bit of the $k\text{th}$ user given as an LLR and which is set to $0$ if no prior knowledge is assumed to be available, and $\sigma (\cdot )$ is the sigmoid function. The definition of the LLR has been chosen such that it is equivalent with that of logit. This is different from many textbooks in communications, where the LLR is defined as $LLR(k,i)=\ln \left(\frac{Pr(b_{k,i}=0|\mathbf{y},\mathbf{H})}{Pr(b_{k,i}=1|\mathbf{y},\mathbf{H})}\right)$.

With the “maxlog” demapping method, the LLR for the $i\text{th}$ bit of the $k\text{th}$ user is approximated like

$$\begin{array}{r}\begin{array}{rl}LLR(k,i)\approx & \ln \left(\frac{\underset{\mathbf{x}\in {\mathcal{C}}_{k,i,1}}{max}(\exp (-{\Vert \tilde{\mathbf{y}}-\tilde{\mathbf{H}}\mathbf{x}\Vert }^2)Pr\left(\mathbf{x}\right))}{\underset{\mathbf{x}\in {\mathcal{C}}_{k,i,0}}{max}(\exp (-{\Vert \tilde{\mathbf{y}}-\tilde{\mathbf{H}}\mathbf{x}\Vert }^2)Pr\left(\mathbf{x}\right))}\right)\\ =& \underset{\mathbf{x}\in {\mathcal{C}}_{k,i,0}}{min}({\Vert \tilde{\mathbf{y}}-\tilde{\mathbf{H}}\mathbf{x}\Vert }^2-\ln (Pr\left(\mathbf{x}\right)))-\underset{\mathbf{x}\in {\mathcal{C}}_{k,i,1}}{min}({\Vert \tilde{\mathbf{y}}-\tilde{\mathbf{H}}\mathbf{x}\Vert }^2-\ln (Pr\left(\mathbf{x}\right))).\end{array}\end{array}$$

ML detection of symbols:

Soft-decisions on symbols are called logits (i.e., unnormalized log-probability).

With the “app” demapping method, the logit for the constellation point $c\in \mathcal{C}$ of the $k\text{th}$ user is computed according to

$$\begin{array}{rl}\text{logit}(k,c)& =\ln (\sum _{\mathbf{x}:x_k=c}\exp (-{\Vert \tilde{\mathbf{y}}-\tilde{\mathbf{H}}\mathbf{x}\Vert }^2)Pr\left(\mathbf{x}\right)).\end{array}$$

With the “maxlog” demapping method, the logit for the constellation point $c\in \mathcal{C}$ of the $k\text{th}$ user is approximated like

$$\text{logit}(k,c)\approx \underset{\mathbf{x}:x_k=c}{max}(-{\Vert \tilde{\mathbf{y}}-\tilde{\mathbf{H}}\mathbf{x}\Vert }^2+\ln (Pr\left(\mathbf{x}\right))).$$

When hard decisions are requested, this block returns for the $k$ th stream

$${\hat{c}}_k=\underset{c\in \mathcal{C}}{\text{argmax}}(\sum _{\mathbf{x}:x_k=c}\exp (-{\Vert \tilde{\mathbf{y}}-\tilde{\mathbf{H}}\mathbf{x}\Vert }^2)Pr\left(\mathbf{x}\right))$$

where $\mathcal{C}$ is the set of constellation points.

Parameters:

• output ("bit" | "symbol") – Type of output, either LLRs on bits or logits on constellation symbols

• demapping_method ("app" | "maxlog") – Demapping method to be used

• num_streams (int) – Number of transmitted streams

• 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 None, constellation_type and num_bits_per_symbol must be provided.

• hard_out (bool, (default False)) – If True, the detector computes hard-decided bit values or constellation point indices 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 ([…,M], tf.complex) – Received signals

• h ([…,M,num_streams], tf.complex) – Channel matrices

• s ([…,M,M], tf.complex) – Noise covariance matrices

• prior (None (default) | […,num_streams,num_bits_per_symbol] or […,num_streams,num_points], tf.float) – Prior of the transmitted signals. If output equals “bit”, then LLRs of the transmitted bits are expected. If output equals “symbol”, then logits of the transmitted constellation points are expected.

Output:

• One of

• […, num_streams, num_bits_per_symbol], tf.float – LLRs or hard-decisions for every bit of every stream, if output equals “bit”.

• […, num_streams, num_points], tf.float or […, num_streams], tf.int32 – Logits or hard-decisions for constellation symbols for every stream, if output equals “symbol”. Hard-decisions correspond to the symbol indices.

class sionna.phy.mimo.MMSEPICDetector(output, demapping_method='maxlog', num_iter=1, constellation_type=None, num_bits_per_symbol=None, constellation=None, hard_out=False, precision=None, **kwargs)

Minimum mean square error (MMSE) with parallel interference cancellation (PIC) detector

This block implements the MMSE PIC detector, as proposed in [CST2011]. For num_iter>1, this implementation performs MMSE PIC self-iterations. MMSE PIC self-iterations can be understood as a concatenation of MMSE PIC detectors from [CST2011], which forward intrinsic LLRs to the next self-iteration.

Compared to [CST2011], this implementation also accepts priors on the constellation symbols as an alternative to priors on the bits.

This block assumes the following channel model:

$$\mathbf{y}=\mathbf{H}\mathbf{x}+\mathbf{n}$$

where $\mathbf{y}\in {\mathbb{C}}^M$ is the received signal vector, $\mathbf{x}\in {\mathcal{C}}^S$ is the vector of transmitted symbols which are uniformly and independently drawn from the constellation $\mathcal{C}$, $\mathbf{H}\in {\mathbb{C}}^{M\times S}$ is the known channel matrix, and $\mathbf{n}\in {\mathbb{C}}^M$ is a complex Gaussian noise vector. It is assumed that $\mathbb{E}\left[\mathbf{n}\right]=\mathbf{0}$ and $\mathbb{E}\left[\mathbf{n}{\mathbf{n}}^{\mathsf{H}}\right]=\mathbf{S}$, where $\mathbf{S}$ has full rank.

The algorithm starts by computing the soft symbols ${\overline{x}}_s=\mathbb{E}\left[x_s\right]$ and variances $v_s=\mathbb{E}\left[|e_s{|}^2\right]$ from the priors, where $e_s=x_s-{\overline{x}}_s$, for all $s=1,\dots ,S$.

Next, for each stream, the interference caused by all other streams is cancelled from the observation $\mathbf{y}$, leading to

$${\hat{\mathbf{y}}}_s=\mathbf{y}-\sum _{j\ne s}{\mathbf{h}}_j{x}_j={\mathbf{h}}_s{x}_s+{\tilde{\mathbf{n}}}_s,s=1,\dots ,S$$

where ${\tilde{\mathbf{n}}}_s=\sum _{j\ne s}{\mathbf{h}}_j{e}_j+\mathbf{n}$.

Then, a linear MMSE filter ${\mathbf{w}}_s$ is computed to reduce the resdiual noise for each observation ${\hat{\mathbf{y}}}_s$, which is given as

$${\mathbf{w}}_s={\mathbf{h}}_s^{\mathsf{H}}{(\mathbf{H}{\mathbf{D}}_s{\mathbf{H}}^{\mathsf{H}}+\mathbf{S})}^{-1}$$

where ${\mathbf{D}}_s\in {\mathbb{C}}^{S\times S}$ is diagonal with entries

$$\begin{array}{r}{\left[{\mathbf{D}}_s\right]}_{i,i}=\{\begin{array}{ll}{v}_i& i\ne s\\ 1& i=s.\end{array}\end{array}$$

The filtered observations

$${\tilde{z}}_s={\mathbf{w}}_s^{\mathsf{H}}{\hat{\mathbf{y}}}_s={\tilde{\mu }}_s{x}_s+{\mathbf{w}}_s^{\mathsf{H}}{\tilde{\mathbf{n}}}_s$$

where ${\tilde{\mu }}_s={\mathbf{w}}_s^{\mathsf{H}}{\mathbf{h}}_s$, are then demapped to either symbol logits or LLRs, assuming that the remaining noise is Gaussian with variance

$${\nu }_s^2=\text{Var}\left[{\tilde{z}}_s\right]={\mathbf{w}}_s^{\mathsf{H}}(\sum _{j\ne s}{\mathbf{h}}_j{\mathbf{h}}_j^{\mathsf{H}}{v}_j+\mathbf{S}){\mathbf{w}}_s.$$

The resulting soft-symbols can then be used for the next self-iteration of the algorithm.

Note that this algorithm can be substantially simplified as described in [CST2011] to avoid the computation of different matrix inverses for each stream. This is the version which is implemented.

Parameters:

• output ("bit" | "symbol") – Type of output, either LLRs on bits or logits on constellation symbols

• demapping_method ("maxlog" (default) | "app") – Demapping method to be used

• num_iter (int, (default 1)) – Number of MMSE PIC iterations

• 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 None, constellation_type and num_bits_per_symbol must be provided.

• hard_out (bool, (default False)) – If True, the detector computes hard-decided bit values or constellation point indices 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 ([…,M], tf.complex) – Received signals

• h ([…,M,num_streams], tf.complex) – Channel matrices

• s ([…,M,M], tf.complex) – Noise covariance matrices

• prior ([…,num_streams,num_bits_per_symbol] or […,num_streams,num_points], tf.float) – Prior of the transmitted signals. If output equals “bit”, then LLRs of the transmitted bits are expected. If output equals “symbol”, then logits of the transmitted constellation points are expected.

Output:

• One of

• […, num_streams, num_bits_per_symbol], tf.float – LLRs or hard-decisions for every bit of every stream, if output equals “bit”.

• […, num_streams, num_points], tf.float or […, num_streams], tf.int32 – Logits or hard-decisions for constellation symbols for every stream, if output equals “symbol”. Hard-decisions correspond to the symbol indices.

Utility Functions

class sionna.phy.mimo.List2LLR(precision=None, **kwargs)

Abstract class defining a callable to compute LLRs from a list of candidate vectors (or paths) provided by a MIMO detector

The following channel model is assumed

$$\overline{\mathbf{y}}=\mathbf{R}\overline{\mathbf{x}}+\overline{\mathbf{n}}$$

where $\overline{\mathbf{y}}\in {\mathbb{C}}^S$ are the channel outputs, $\mathbf{R}\in {\mathbb{C}}^{S\times S}$ is an upper-triangular matrix, $\overline{\mathbf{x}}\in {\mathbb{C}}^S$ is the transmitted vector whose entries are uniformly and independently drawn from the constellation $\mathcal{C}$, and $\overline{\mathbf{n}}\in {\mathbb{C}}^S$ is white noise with $\mathbb{E}\left[\overline{\mathbf{n}}\right]=\mathbf{0}$ and $\mathbb{E}\left[\overline{\mathbf{n}}{\overline{\mathbf{n}}}^{\mathsf{H}}\right]=\mathbf{I}$.

It is assumed that a MIMO detector such as KBestDetector produces $K$ candidate solutions ${\overline{\mathbf{x}}}_k\in {\mathcal{C}}^S$ and their associated distance metrics $d_k=\Vert \overline{\mathbf{y}}-\mathbf{R}{\overline{\mathbf{x}}}_k{\Vert }^2$ for $k=1,\dots ,K$. This layer can also be used with the real-valued representation of the channel.

Parameters:

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

Input:

• y ([…,M], tf.complex or tf.float) – Channel outputs of the whitened channel

• r ([…,num_streams, num_streams], same dtype as y) – Upper triangular channel matrix of the whitened channel

• dists ([…,num_paths], tf.float) – Distance metric for each path (or candidate)

• path_inds ([…,num_paths,num_streams], tf.int32) – Symbol indices for every stream of every path (or candidate)

• path_syms ([…,num_path,num_streams], same dtype as y) – Constellation symbol for every stream of every path (or candidate)

Output:

llr ([…num_streams,num_bits_per_symbol], tf.float) – LLRs for all bits of every stream

Note

An implementation of this class does not need to make use of all of the provided inputs which enable various different implementations.

class sionna.phy.mimo.List2LLRSimple(num_bits_per_symbol, llr_clip_val=20.0, precision=None, **kwargs)

Computes LLRs from a list of candidate vectors (or paths) provided by a MIMO detector

The following channel model is assumed:

$$\overline{\mathbf{y}}=\mathbf{R}\overline{\mathbf{x}}+\overline{\mathbf{n}}$$

where $\overline{\mathbf{y}}\in {\mathbb{C}}^S$ are the channel outputs, $\mathbf{R}\in {\mathbb{C}}^{S\times S}$ is an upper-triangular matrix, $\overline{\mathbf{x}}\in {\mathbb{C}}^S$ is the transmitted vector whose entries are uniformly and independently drawn from the constellation $\mathcal{C}$, and $\overline{\mathbf{n}}\in {\mathbb{C}}^S$ is white noise with $\mathbb{E}\left[\overline{\mathbf{n}}\right]=\mathbf{0}$ and $\mathbb{E}\left[\overline{\mathbf{n}}{\overline{\mathbf{n}}}^{\mathsf{H}}\right]=\mathbf{I}$.

It is assumed that a MIMO detector such as KBestDetector produces $K$ candidate solutions ${\overline{\mathbf{x}}}_k\in {\mathcal{C}}^S$ and their associated distance metrics $d_k=\Vert \overline{\mathbf{y}}-\mathbf{R}{\overline{\mathbf{x}}}_k{\Vert }^2$ for $k=1,\dots ,K$. This layer can also be used with the real-valued representation of the channel.

The LLR for the $i\text{th}$ bit of the $k\text{th}$ stream is computed as

$$\begin{array}{r}\begin{array}{rl}LLR(k,i)& =\log \left(\frac{Pr(b_{k,i}=1|\overline{\mathbf{y}},\mathbf{R})}{Pr(b_{k,i}=0|\overline{\mathbf{y}},\mathbf{R})}\right)\\ & \approx \underset{j\in {\mathcal{C}}_{k,i,0}}{min}{d}_j-\underset{j\in {\mathcal{C}}_{k,i,1}}{min}{d}_j\end{array}\end{array}$$

where ${\mathcal{C}}_{k,i,1}$ and ${\mathcal{C}}_{k,i,0}$ are the set of indices in the list of candidates for which the $i\text{th}$ bit of the $k\text{th}$ stream is equal to 1 and 0, respectively. The LLRs are clipped to $\pm LL{R}_{\text{clip}}$ which can be configured through the parameter llr_clip_val.

If ${\mathcal{C}}_{k,i,0}$ is empty, $LLR(k,i)=LL{R}_{\text{clip}}$; if ${\mathcal{C}}_{k,i,1}$ is empty, $LLR(k,i)=-LL{R}_{\text{clip}}$.

Parameters:

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

• llr_clip_val (float, (default 20.0)) – The absolute values of LLRs are clipped to this value.

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

Input:

• y ([…,M], tf.complex or tf.float) – Channel outputs of the whitened channel

• r ([…,num_streams, num_streams], same dtype as y) – Upper triangular channel matrix of the whitened channel

• dists ([…,num_paths], tf.float) – Distance metric for each path (or candidate)

• path_inds ([…,num_paths,num_streams], tf.int32) – Symbol indices for every stream of every path (or candidate)

• path_syms ([…,num_path,num_streams], same dtype as y) – Constellation symbol for every stream of every path (or candidate)

Output:

llr ([…num_streams,num_bits_per_symbol], tf.float) – LLRs for all bits of every stream

property llr_clip_val

Get/set the value to which the absolute values of LLRs are clipped

Type:

float

sionna.phy.mimo.complex2real_vector(z)

Transforms a complex-valued vector into its real-valued equivalent

Transforms the last dimension of a complex-valued tensor into its real-valued equivalent by stacking the real and imaginary parts on top of each other.

For a vector $\mathbf{z}\in {\mathbb{C}}^M$ with real and imaginary parts $\mathbf{x}\in {\mathbb{R}}^M$ and $\mathbf{y}\in {\mathbb{R}}^M$, respectively, this function returns the vector ${[{\mathbf{x}}^{\mathsf{T}},{\mathbf{y}}^{\mathsf{T}}]}^{\mathsf{T}}\in {\mathbb{R}}^{2M}$.

Input:

[…,M], tf.complex

Output:

[…,2M], tf.complex.real_dtype

sionna.phy.mimo.real2complex_vector(z)

Transforms a real-valued vector into its complex-valued equivalent

Transforms the last dimension of a real-valued tensor into its complex-valued equivalent by interpreting the first half as the real and the second half as the imaginary part.

For a vector $\mathbf{z}={[{\mathbf{x}}^{\mathsf{T}},{\mathbf{y}}^{\mathsf{T}}]}^{\mathsf{T}}\in {\mathbb{R}}^{2M}$ with $\mathbf{x}\in {\mathbb{R}}^M$ and $\mathbf{y}\in {\mathbb{R}}^M$, this function returns the vector $\mathbf{x}+j\mathbf{y}\in {\mathbb{C}}^M$.

Input:

[…,2M], tf.float

Output:

[…,M], tf.complex

sionna.phy.mimo.complex2real_matrix(z)

Transforms a complex-valued matrix into its real-valued equivalent

Transforms the last two dimensions of a complex-valued tensor into their real-valued matrix equivalent representation.

For a matrix $\mathbf{Z}\in {\mathbb{C}}^{M\times K}$ with real and imaginary parts $\mathbf{X}\in {\mathbb{R}}^{M\times K}$ and $\mathbf{Y}\in {\mathbb{R}}^{M\times K}$, respectively, this function returns the matrix $\tilde{\mathbf{Z}}\in {\mathbb{R}}^{2M\times 2K}$, given as

$$\begin{array}{r}\tilde{\mathbf{Z}}=\left(\begin{array}{cc}\mathbf{X}& -\mathbf{Y}\\ \mathbf{Y}& \mathbf{X}\end{array}\right).\end{array}$$

Input:

[…,M,K], tf.complex

Output:

[…,2M, 2K], tf.complex.real_dtype

sionna.phy.mimo.real2complex_matrix(z)

Transforms a real-valued matrix into its complex-valued equivalent

Transforms the last two dimensions of a real-valued tensor into their complex-valued matrix equivalent representation.

For a matrix $\tilde{\mathbf{Z}}\in {\mathbb{R}}^{2M\times 2K}$, satisfying

$$\begin{array}{r}\tilde{\mathbf{Z}}=\left(\begin{array}{cc}\mathbf{X}& -\mathbf{Y}\\ \mathbf{Y}& \mathbf{X}\end{array}\right)\end{array}$$

with $\mathbf{X}\in {\mathbb{R}}^{M\times K}$ and $\mathbf{Y}\in {\mathbb{R}}^{M\times K}$, this function returns the matrix $\mathbf{Z}=\mathbf{X}+j\mathbf{Y}\in {\mathbb{C}}^{M\times K}$.

Input:

[…,2M,2K], tf.float

Output:

[…,M, 2], tf.complex

sionna.phy.mimo.complex2real_covariance(r)

Transforms a complex-valued covariance matrix to its real-valued equivalent

Assume a proper complex random variable $\mathbf{z}\in {\mathbb{C}}^M$ [ProperRV] with covariance matrix $\mathbf{R}=\in {\mathbb{C}}^{M\times M}$ and real and imaginary parts $\mathbf{x}\in {\mathbb{R}}^M$ and $\mathbf{y}\in {\mathbb{R}}^M$, respectively. This function transforms the given $\mathbf{R}$ into the covariance matrix of the real-valued equivalent vector $\tilde{\mathbf{z}}={[{\mathbf{x}}^{\mathsf{T}},{\mathbf{y}}^{\mathsf{T}}]}^{\mathsf{T}}\in {\mathbb{R}}^{2M}$, which is computed as [CovProperRV]

$$\begin{array}{r}\mathbb{E}\left[\tilde{\mathbf{z}}{\tilde{\mathbf{z}}}^{\mathsf{H}}\right]=\left(\begin{array}{cc}\frac{1}{2}\mathrm{\Re }\{\mathbf{R}\}& -\frac{1}{2}\mathrm{\Im }\{\mathbf{R}\}\\ \frac{1}{2}\mathrm{\Im }\{\mathbf{R}\}& \frac{1}{2}\mathrm{\Re }\{\mathbf{R}\}\end{array}\right).\end{array}$$

Input:

[…,M,M], tf.complex

Output:

[…,2M, 2M], tf.complex.real_dtype

sionna.phy.mimo.real2complex_covariance(q)

Transforms a real-valued covariance matrix to its complex-valued equivalent

Assume a proper complex random variable $\mathbf{z}\in {\mathbb{C}}^M$ [ProperRV] with covariance matrix $\mathbf{R}=\in {\mathbb{C}}^{M\times M}$ and real and imaginary parts $\mathbf{x}\in {\mathbb{R}}^M$ and $\mathbf{y}\in {\mathbb{R}}^M$, respectively. This function transforms the given covariance matrix of the real-valued equivalent vector $\tilde{\mathbf{z}}={[{\mathbf{x}}^{\mathsf{T}},{\mathbf{y}}^{\mathsf{T}}]}^{\mathsf{T}}\in {\mathbb{R}}^{2M}$, which is given as [CovProperRV]

$$\begin{array}{r}\mathbb{E}\left[\tilde{\mathbf{z}}{\tilde{\mathbf{z}}}^{\mathsf{H}}\right]=\left(\begin{array}{cc}\frac{1}{2}\mathrm{\Re }\{\mathbf{R}\}& -\frac{1}{2}\mathrm{\Im }\{\mathbf{R}\}\\ \frac{1}{2}\mathrm{\Im }\{\mathbf{R}\}& \frac{1}{2}\mathrm{\Re }\{\mathbf{R}\}\end{array}\right),\end{array}$$

into is complex-valued equivalent $\mathbf{R}$.

Input:

[…,2M,2M], tf.float

Output:

[…,M, M], tf.complex

sionna.phy.mimo.complex2real_channel(y, h, s)

Transforms a complex-valued MIMO channel into its real-valued equivalent

Assume the canonical MIMO channel model

$$\mathbf{y}=\mathbf{H}\mathbf{x}+\mathbf{n}$$

where $\mathbf{y}\in {\mathbb{C}}^M$ is the received signal vector, $\mathbf{x}\in {\mathbb{C}}^K$ is the vector of transmitted symbols, $\mathbf{H}\in {\mathbb{C}}^{M\times K}$ is the known channel matrix, and $\mathbf{n}\in {\mathbb{C}}^M$ is a noise vector with covariance matrix $\mathbf{S}\in {\mathbb{C}}^{M\times M}$.

This function returns the real-valued equivalent representations of $\mathbf{y}$, $\mathbf{H}$, and $\mathbf{S}$, which are used by a wide variety of MIMO detection algorithms (Section VII) [YH2015]. These are obtained by applying complex2real_vector() to $\mathbf{y}$, complex2real_matrix() to $\mathbf{H}$, and complex2real_covariance() to $\mathbf{S}$.

Input:

• y ([…,M], tf.complex) – Complex-valued received signals

• h ([…,M,K], tf.complex) – Complex-valued channel matrices

• s ([…,M,M], tf.complex) – Complex-valued noise covariance matrices

Output:

• […,2M], tf.complex.real_dtype – Real-valued equivalent received signals

• […,2M,2K], tf.complex.real_dtype – Real-valued equivalent channel matrices

• […,2M,2M], tf.complex.real_dtype – Real-valued equivalent noise covariance matrices

sionna.phy.mimo.real2complex_channel(y, h, s)

Transforms a real-valued MIMO channel into its complex-valued equivalent

Assume the canonical MIMO channel model

$$\mathbf{y}=\mathbf{H}\mathbf{x}+\mathbf{n}$$

where $\mathbf{y}\in {\mathbb{C}}^M$ is the received signal vector, $\mathbf{x}\in {\mathbb{C}}^K$ is the vector of transmitted symbols, $\mathbf{H}\in {\mathbb{C}}^{M\times K}$ is the known channel matrix, and $\mathbf{n}\in {\mathbb{C}}^M$ is a noise vector with covariance matrix $\mathbf{S}\in {\mathbb{C}}^{M\times M}$.

This function transforms the real-valued equivalent representations of $\mathbf{y}$, $\mathbf{H}$, and $\mathbf{S}$, as, e.g., obtained with the function complex2real_channel(), back to their complex-valued equivalents (Section VII) [YH2015].

Input:

• y ([…,2M], tf.float) – Real-valued received signals

• h ([…,2M,2K], tf.float) – Real-valued channel matrices

• s ([…,2M,2M], tf.float) – Real-valued noise covariance matrices

Output:

• […,M], tf.complex – Complex-valued equivalent received signals

• […,M,K], tf.complex – Complex-valued equivalent channel matrices

• […,M,M], tf.complex – Complex-valued equivalent noise covariance matrices

sionna.phy.mimo.whiten_channel(y, h, s, return_s=True)

Whitens a canonical MIMO channel

Assume the canonical MIMO channel model

$$\mathbf{y}=\mathbf{H}\mathbf{x}+\mathbf{n}$$

where $\mathbf{y}\in {\mathbb{C}}^M({\mathbb{R}}^M)$ is the received signal vector, $\mathbf{x}\in {\mathbb{C}}^K({\mathbb{R}}^K)$ is the vector of transmitted symbols, $\mathbf{H}\in {\mathbb{C}}^{M\times K}({\mathbb{R}}^{M\times K})$ is the known channel matrix, and $\mathbf{n}\in {\mathbb{C}}^M({\mathbb{R}}^M)$ is a noise vector with covariance matrix $\mathbf{S}\in {\mathbb{C}}^{M\times M}({\mathbb{R}}^{M\times M})$.

This function whitens this channel by multiplying $\mathbf{y}$ and $\mathbf{H}$ from the left by ${\mathbf{S}}^{-\frac{1}{2}}={\mathbf{L}}^{-1}$, where $\mathbf{L}\in {\mathbb{C}}^{M\times M}$ is the Cholesky decomposition of $\mathbf{S}$. Optionally, the whitened noise covariance matrix ${\mathbf{I}}_M$ can be returned.

Input:

• y ([…,M], tf.float or tf.complex) – Received signals

• h ([…,M,K], tf.float or tf.complex) – Channel matrices

• s ([…,M,M], tf.float or tf.complex) – Noise covariance matrices

• return_s (bool, (default True)) – If True, the whitened covariance matrix is returned.

Output:

• […,M], tf.float or tf.complex – Whitened received signals

• […,M,K], tf.float or tf.complex – Whitened channel matrices

• […,M,M], tf.float or tf.complex – Whitened noise covariance matrices. Only returned if return_s is True.

References:

[ProperRV] (1,2)

Proper complex random variables, Wikipedia, accessed 11 September, 2022.

[CovProperRV] (1,2)

Covariance matrices of real and imaginary parts, Wikipedia, accessed 11 September, 2022.

[YH2015] (1,2)

S. Yang and L. Hanzo, “Fifty Years of MIMO Detection: The Road to Large-Scale MIMOs”, IEEE Communications Surveys & Tutorials, vol. 17, no. 4, pp. 1941-1988, 2015.

[FT2015]

W. Fu and J. S. Thompson, “Performance analysis of K-best detection with adaptive modulation”, IEEE Int. Symp. Wirel. Commun. Sys. (ISWCS), 2015.

[EP2014]

J. Céspedes, P. M. Olmos, M. Sánchez-Fernández, and F. Perez-Cruz, “Expectation Propagation Detection for High-Order High-Dimensional MIMO Systems”, IEEE Trans. Commun., vol. 62, no. 8, pp. 2840-2849, Aug. 2014.

[CST2011] (1,2,3,4)

C. Studer, S. Fateh, and D. Seethaler, “ASIC Implementation of Soft-Input Soft-Output MIMO Detection Using MMSE Parallel Interference Cancellation”, IEEE Journal of Solid-State Circuits, vol. 46, no. 7, pp. 1754–1765, July 2011.