Struct Constellation 

pub struct Constellation { /* private fields */ }

A labelled constellation: points()[i] carries the bits of i.

Implementations

impl Constellation

pub fn new(kind: ConstellationKind, m: usize) -> Result<Constellation>

The constellation of a family and an order m (power of two; a square for QAM; 2 for OOK).

Errors

Error::Config unless m is a power of two ≥ 2 (a square for QAM).

pub fn qam(m: usize) -> Result<Constellation>

Square m-QAM (m = 4, 16, 64, 256, …).

Errors

Error::Config unless m is an even power of two ≥ 4.

pub fn psk(m: usize) -> Result<Constellation>

m-PSK.

Errors

Error::Config unless m is a power of two ≥ 2.

pub fn pam(m: usize) -> Result<Constellation>

m-PAM.

Errors

Error::Config unless m is a power of two ≥ 2.

pub fn ook() -> Constellation

On-off keying.

pub fn from_name(name: &str) -> Result<Constellation>

The constellation of a name: 16-QAM, qam16, QPSK (4-QAM), BPSK (2-PSK), 8-PSK, 4-PAM, OOK (case-insensitive; -, _ and spaces are ignored), not normalised (call Constellation::normalized for unit energy).

Errors

Error::Config for an unknown family, a missing order or an invalid one.

Examples

use comnum_mapping::constellation::{Constellation, ConstellationKind};
let c = Constellation::from_name("16-QAM")?;
assert_eq!((c.kind(), c.order()), (ConstellationKind::Qam, 16));
assert_eq!(Constellation::from_name("qpsk")?, Constellation::qam(4)?);
assert!(Constellation::from_name("sixteen").is_err());

pub fn from_points(points: Vec<C64>) -> Result<Constellation>

A constellation from its points, points[i] labelled by the bits of i.

Errors

Error::Config unless the number of points is a power of two ≥ 2.

pub fn set_partitioning( kind: ConstellationKind, m: usize, ) -> Result<Constellation>

The same points as Constellation::new with a set-partitioning labelling (Ungerboeck 1982): fixing the last bits of the label leaves subsets whose minimum distance grows. PSK gets the natural labelling, the point $e^{j2\pi k/M}$ carrying the bits of $k$; 16-QAM the labelling of Caire, Taricco & Biglieri (IEEE Trans. Inf. Theory 44(3), 1998, Fig. 2(a)). The family of the result is ConstellationKind::Custom.

Errors

Error::Config for another family or order.

Examples

use comnum_mapping::constellation::{Constellation, ConstellationKind};
use comnum_math::C64;
let c = Constellation::set_partitioning(ConstellationKind::Qam, 16)?;
assert_eq!(c.points()[0b1001], C64::new(-3.0, 3.0));
// the points ending in 00 form a 4-QAM of side 4
let sub: Vec<C64> = (0..16).filter(|i| i & 3 == 0).map(|i| c.points()[i]).collect();
assert!(sub.iter().all(|a| sub.iter().all(|b| a == b || (a - b).norm() >= 4.0)));

pub fn kind(&self) -> ConstellationKind

The family.

pub fn order(&self) -> usize

The number of points M.

pub fn bits_per_symbol(&self) -> usize

Bits per symbol log2 M.

pub fn points(&self) -> &[C64]

The points, indexed by their label.

pub fn energy(&self) -> f64

Average energy Σ |x_i|² / M (uniform probabilities).

pub fn energy_with(&self, px: &[f64]) -> Result<f64>

Average energy Σ p_i |x_i|² under the probabilities px.

Errors

Error::Shape unless px holds one probability per point.

pub fn priors(&self, px: Option<&[f64]>) -> Result<Vec<f64>>

The prior probabilities of the points: px checked (one non-negative value per point, not all zero) and normalised to a sum of 1, or uniform if None.

Errors

Error::Shape for another number of values, Error::Config for negative or all-zero values.

pub fn normalized_under(&self, px: &[f64]) -> Result<Constellation>

The same constellation scaled to unit average energy under the probabilities px (probabilistic shaping), normalised to a sum of 1 first as by Constellation::priors.

Errors

As Constellation::priors; Error::Config if the energy under px is zero.

pub fn normalized(&self) -> Constellation

The same constellation scaled to unit average energy.

pub fn scaled(&self, s: f64) -> Constellation

The same constellation with every point multiplied by s.

pub fn indices(&self, bits: &[u8]) -> Result<Vec<usize>>

The label (index) of every symbol of a bit stream (most significant bit first).

Errors

Error::Shape if the number of bits is not a multiple of log2 M.

pub fn map_bits(&self, bits: &[u8]) -> Result<Vec<C64>>

Map a bit stream to symbols (OptiCommPy modulateGray).

Errors

Error::Shape if the number of bits is not a multiple of log2 M.

pub fn symbols(&self, indices: &[usize]) -> Vec<C64>

The symbols of a sequence of labels.

pub fn decide(&self, z: &[C64]) -> Vec<usize>

The label of the nearest point of every sample (minimum Euclidean distance).

pub fn nearest(&self, z: C64) -> usize

The label of the point nearest to z.

pub fn project(&self, z: &[C64]) -> Vec<C64>

The nearest point of every sample.

pub fn demap_bits(&self, z: &[C64]) -> Vec<u8>

Hard-decision bits of every sample (OptiCommPy demodulateGray).

impl Constellation

pub fn llr( &self, z: &[C64], noise_var: f64, px: Option<&[f64]>, jacobian: Jacobian, ) -> Result<Vec<f64>>

Log-likelihood ratios of the bits, b per symbol (see the module documentation).

noise_var is the variance of the complex noise E|w|² (for a real constellation over a real channel, pass twice the variance of the real noise, as OptiCommPy does); px are the prior probabilities of the points (uniform if None, normalised otherwise).

Errors

comnum_core::Error::Config for a noise variance that is not positive, comnum_core::Error::Shape for priors of another length than the constellation, comnum_core::Error::Config for negative or all-zero priors.

pub fn llr_into( &self, z: &[C64], noise_var: f64, px: Option<&[f64]>, jacobian: Jacobian, out: &mut [f64], ) -> Result<()>

Constellation::llr into the z.len() log2 M values of out (no allocation with uniform priors up to STACK_POINTS points).

Errors

As Constellation::llr, and comnum_core::Error::Shape for an out of another length.

Examples

use comnum_mapping::constellation::Constellation;
use comnum_math::Jacobian;
let c = Constellation::qam(16)?.normalized();
let z = [c.points()[5], c.points()[12]];
let mut out = [0.0; 8];
c.llr_into(&z, 0.1, None, Jacobian::Exact, &mut out)?;
assert_eq!(out[..], c.llr(&z, 0.1, None, Jacobian::Exact)?[..]);

pub fn llr_with_variances( &self, z: &[C64], noise_vars: &[f64], px: Option<&[f64]>, jacobian: Jacobian, ) -> Result<Vec<f64>>

Constellation::llr with one noise variance per symbol, noise_vars[i] that of z[i] (the output of a linear detector, of Alamouti’s combiner).

Errors

As Constellation::llr, and comnum_core::Error::Shape for one variance per symbol missing.

Examples

use comnum_mapping::constellation::Constellation;
use comnum_math::Jacobian;
let c = Constellation::qam(4)?.normalized();
let z = [c.points()[0], c.points()[3]];
let both = c.llr_with_variances(&z, &[0.1, 0.4], None, Jacobian::Exact)?;
assert_eq!(both[2..], c.llr(&z[1..], 0.4, None, Jacobian::Exact)?[..]);

pub fn llr_with_variances_into( &self, z: &[C64], noise_vars: &[f64], px: Option<&[f64]>, jacobian: Jacobian, out: &mut [f64], ) -> Result<()>

Constellation::llr_with_variances into the z.len() log2 M values of out.

Errors

As Constellation::llr_with_variances, and comnum_core::Error::Shape for an out of another length.

Trait Implementations

impl Clone for Constellation

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Constellation

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Demap for Constellation

The soft demapper of the constellation: the kernel of Constellation::llr_into on every stream, with the log-priors and the logarithm of the Demapping.

fn demap_with_into( &self, y: &Symbols, noise_var: f64, demapping: Demapping<'_>, out: &mut Llr, ) -> Result<()>

Errors

comnum_core::Error::Config for a noise variance that is not positive and finite, or log-priors with a NaN or $+\infty$, or none finite; comnum_core::Error::Shape for log-priors of another length than the constellation.

fn demap_into( &self, y: &Symbols, noise_var: f64, out: &mut Llr, ) -> Result<(), Error>

Demap y, received with a complex noise variance noise_var, into out: the exact LLRs under uniform priors (Demap::demap_with_into with the default Demapping).

fn demap_with( &self, y: &Symbols, noise_var: f64, demapping: Demapping<'_>, ) -> Result<Llr, Error>

Demap y with demapping (allocates, calls Demap::demap_with_into).

fn demap(&self, y: &Symbols, noise_var: f64) -> Result<Llr, Error>

Demap y (allocates, calls Demap::demap_into).

impl Map for Constellation

fn map_into(&self, bits: &Bits, out: &mut Symbols) -> Result<()>

Map bits into out.

fn map(&self, bits: &Bits) -> Result<Symbols, Error>

Map bits (allocates, calls Map::map_into).

impl PartialEq for Constellation

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Constellation