komm.Constellation

General real or complex constellation. A constellation of dimension $N$ and order $M$ is defined by an ordered set $\{ \mathbf{x}_i : i \in [0:M) \}$ of $M$ distinct points in $\mathbb{R}^N$ or $\mathbb{C}^N$, called symbols. In this class, the constellation is represented by a matrix $\mathbf{X} \in \mathbb{R}^{M \times N}$ or $\mathbf{X} \in \mathbb{C}^{M \times N}$, where the $i$-th row of $\mathbf{X}$ corresponds to symbol $\mathbf{x}_i$. For more details, see SA15, Sec. 2.5.1.

Parameters:

• matrix (ArrayLike) –

  The constellation matrix $\mathbf{X}$. Must be a 2D-array of shape $(M, N)$ with real or complex entries.

Examples:

The real constellation depicted in the figure below has $M = 5$ and $N = 2$.

>>> const = komm.Constellation([[0, 4], [-2, 2], [2, 2], [1, 1], [0, -2]])

matrix Array2D[T] property

The constellation matrix $\mathbf{X}$.

Examples:

>>> const = komm.Constellation([[0, 4], [-2, 2], [2, 2], [1, 1], [0, -2]])
>>> const.matrix
array([[ 0.,  4.],
       [-2.,  2.],
       [ 2.,  2.],
       [ 1.,  1.],
       [ 0., -2.]])

order int property

The order $M$ of the constellation.

Examples:

>>> const = komm.Constellation([[0, 4], [-2, 2], [2, 2], [1, 1], [0, -2]])
>>> const.order
5

dimension int property

The dimension $N$ of the constellation.

Examples:

>>> const = komm.Constellation([[0, 4], [-2, 2], [2, 2], [1, 1], [0, -2]])
>>> const.dimension
2

mean()

Computes the mean $\mathbf{m}$ of the constellation given prior probabilities $p_i$ of the constellation symbols. It is given by $$ \mathbf{m} = \sum_{i \in [0:M)} p_i \mathbf{x}_i. $$

Parameters:

• priors (ArrayLike | None) –

  The prior probabilities of the constellation symbols. Must be a 1D-array whose size is equal to the order $M$ of the constellation. If not given, uniform priors are assumed.

Returns:

• mean (Array1D[T]) –

  The mean $\mathbf{m}$ of the constellation.

Examples:

>>> const = komm.Constellation([[0, 4], [-2, 2], [2, 2], [1, 1], [0, -2]])
>>> const.mean()
array([0.2, 1.4])

mean_energy()

Computes the mean energy $E$ of the constellation given prior probabilities $p_i$ of the constellation symbols. It is given by $$ E = \sum_{i \in [0:M)} p_i \lVert \mathbf{x}_i \rVert^2. $$

Parameters:

• priors (ArrayLike | None) –

  The prior probabilities of the constellation symbols. Must be a 1D-array whose size is equal to the order $M$ of the constellation. If not given, uniform priors are assumed.

Returns:

• mean_energy (floating) –

  The mean energy $E$ of the constellation.

Examples:

>>> const = komm.Constellation([[0, 4], [-2, 2], [2, 2], [1, 1], [0, -2]])
>>> const.mean_energy()
np.float64(7.6)

minimum_distance()

Computes the minimum Euclidean distance $d_\mathrm{min}$ of the constellation. It is given by $$ d_\mathrm{min} = \min_ { i, j \in [0:M), ~ i \neq j } \lVert \mathrm{x}_i - \mathrm{x}_j \rVert. $$

Examples:

>>> const = komm.Constellation([[0, 4], [-2, 2], [2, 2], [1, 1], [0, -2]])
>>> const.minimum_distance()
np.float64(1.4142135623730951)

indices_to_symbols()

Returns the constellation symbols corresponding to the given indices.

Parameters:

• indices (ArrayLike) –

  The indices to be converted to symbols. Must be an array of integers in $[0:M)$.

Returns:

• symbols (NDArray[T]) –

  The symbols corresponding to the given indices. Has the same shape as indices, but with the last dimension expanded by a factor of $N$.

Examples:

>>> const = komm.Constellation([[0, 4], [-2, 2], [2, 2], [1, 1], [0, -2]])
>>> const.indices_to_symbols([3, 0])
array([1., 1., 0., 4.])
>>> const.indices_to_symbols([[3, 0], [1, 2]])
array([[ 1.,  1.,  0.,  4.],
       [-2.,  2.,  2.,  2.]])

closest_indices()

Returns the indices of the constellation symbols closest to the given received points.

Parameters:

• received (ArrayLike) –

  The received points. Must be an array whose last dimension is a multiple of $N$.

Returns:

• indices (NDArray[integer]) –

  The indices of the symbols closest to the received points. Has the same shape as received, but with the last dimension contracted by a factor of $N$.

Examples:

>>> const = komm.Constellation([[0, 4], [-2, 2], [2, 2], [1, 1], [0, -2]])
>>> const.closest_indices([0.3, 1.8, 0.0, 5.0])
array([3, 0])
>>> const.closest_indices([[0.3, 1.8], [0.0, 5.0]])
array([[3],
       [0]])

closest_symbols()

Returns the constellation symbols closest to the given received points.

Parameters:

• received (ArrayLike) –

  The received points. Must be an array whose last dimension is a multiple of $N$.

Returns:

• symbols (NDArray[T]) –

  The symbols closest to the received points. Has the same shape as received.

Examples:

>>> const = komm.Constellation([[0, 4], [-2, 2], [2, 2], [1, 1], [0, -2]])
>>> const.closest_symbols([0.3, 1.8, 0.0, 5.0])
array([1., 1., 0., 4.])
>>> const.closest_symbols([[0.3, 1.8], [0.0, 5.0]])
array([[1., 1.], [0., 4.]])

posteriors()

Returns the posterior probabilities of each constellation symbol given received points, the signal-to-noise ratio (SNR), and prior probabilities.

Parameters:

• received (ArrayLike) –

  The received points. Must be an array whose last dimension is a multiple of $N$.

• snr (float) –

  The signal-to-noise ratio (SNR) of the channel (linear, not decibel).

• priors (ArrayLike | None) –

  The prior probabilities of the symbols. Must be a 1D-array whose size is equal to $M$. If not given, uniform priors are assumed.

Returns:

• posteriors (NDArray[floating]) –

  The posterior probabilities of each symbol given the received points. Has the same shape as received, but with the last dimension changed by a factor of $M / N$.

Examples:

>>> const = komm.Constellation([[0, 4], [-2, 2], [2, 2], [1, 1], [0, -2]])
>>> const.posteriors([0.3, 1.8, 0.0, 5.0], snr=2.0).round(4)
array([0.1565, 0.1408, 0.2649, 0.4253, 0.0125,
       0.9092, 0.0387, 0.0387, 0.0135, 0.    ])
>>> const.posteriors([[0.3, 1.8], [0.0, 5.0]], snr=2.0).round(4)
array([[0.1565, 0.1408, 0.2649, 0.4253, 0.0125],
       [0.9092, 0.0387, 0.0387, 0.0135, 0.    ]])