mokka.mapping

Module implementing mapping and demapping.

NumPy implementation of Mappers and Demappers.

class mokka.mapping.numpy.QAM(m)

Bases: object

Arbitrarily sized QAM constellation with gray mapping.

Parameters:

m – Information per symbol [bit/symbol]

__init__(m)

Construct QAM class.

get_constellation()

Return all constellation symbols.

The index represents the integer representation of the encoded bit-string (LSB first).

Returns:

all constellation symbols

map(bits)

Perform mapping of bitstrings.

Returns:

complex symbol per bitstring of length self.m

PyTorch implementation of Mappers and Demappers.

class mokka.mapping.torch.ClassicalDemapper(noise_sigma, constellation, optimize=False, bitwise=True, p_symbols=None)

Bases: Module

Classical Bitwise Soft Demapper with Gaussian Noise assumption.

It takes the noise_sigma and constellation sorted from [0,2**m -1] and constructs an more or less efficient demapper which outputs LLRS for all m bits for each received symbol

Parameters:

  • noise_sigma – $\sigma$ for the Gaussian assumption

  • constellation – PyTorch tensor of complex constellation symbols

  • optimize – Use $\sigma$ as trainable paramater

  • bitwise – Perform demapping bitwise returning LLRs

  • p_symbols – PyTorch tensor with symbol probabilities

__init__(noise_sigma, constellation, optimize=False, bitwise=True, p_symbols=None)

Construct ClassicalDemapper.

forward(y, *args)

Perform bitwise demapping of complex symbols.

Params y:

Received complex symbols of dimension batch_size x 1

Returns:

log likelihood ratios

forward_bitwise(dist)

Perform bitwise demapping of complex symbols.

Params y:

Received complex symbols of dimension batch_size x 1

Returns:

log likelihood ratios

forward_symbolwise(dist, *args)

Perform symbolwise soft demapping of complex symbols.

Params y:

Received complex symbols

Returns:

q-values for each constellation symbol

update_constellation(constellation)

Update saved constellation.

class mokka.mapping.torch.ConstellationDemapper(m, depth=3, width=128, with_logit=True, bitwise=True, demod_extra_params=None)

Bases: Module

Demap from a complex input with optional SNR to an output with m-Levels with trainable neural networks.

Parameters:

m – Bits per symbol

Params depth:

Number of hidden layers

Params width:

Neurons per layer

Params with_logit:

Output LLRS and not bit probabilities

Params bitwise:

Bitwise LLRs & probabilities

__init__(m, depth=3, width=128, with_logit=True, bitwise=True, demod_extra_params=None)

Construct ConstellationDemapper.

forward(y, *args)

Perform bitwise demapping of complex symbols.

Returns:

Approximated log likelihood ratio of dimension self.m

static load_model(model_dict, with_logit=True)

Load saved weights.

Parameters:

model_dict – dictionary loaded with torch.load()

class mokka.mapping.torch.ConstellationMapper(m, mod_extra_params=None, center_constellation=False, normalize=True, qam_init=False)

Bases: Module

Mapper which maps from bits in float 0,1 representation to Symbols in the complex plane.

Parameters:

  • m – bits per symbol

  • mod_extra_params – index of extra parameters to feed the NN

  • center_constellation – Apply operation at the end to center constellation

  • normalize – Apply normalization to unit energy

  • qam_init – Initialize the weights to form a Gray mapped QAM constellation

__init__(m, mod_extra_params=None, center_constellation=False, normalize=True, qam_init=False)

Construct ConstellationMapper.

forward(b, *args, one_hot=False)

Perform mapping of bitstrings.

By specifying one_hot=true symbol-wise geometric constellation shaping is possible calculating the loss w.r.t MI after demapping.

Params b:

input to ConstellationMapper either bits or one-hot vectors

Params one_hot:

specify if b is a one-hot vector

Returns:

complex symbol per bitstring of length self.m

get_constellation(*args)

Return constellation for all input bits.

Params args:

same arguments as for forward() if constellation mapper is parametrized

Returns:

tensor of constellation points

static load_model(model_dict)

Load saved weights.

Parameters:

model_dict – dictionary loaded with torch.load()

class mokka.mapping.torch.CustomConstellationMapper(m, constellation_symbols)

Bases: Module

Non-trainable custom constellation Mapper.

__init__(m, constellation_symbols)

Construct CustomConstellationMapper.

forward(b, *args)

Perform mapping of bitstrings.

Returns:

complex symbol per bitstring of length self.m

get_constellation(*args)

Return all constellation symbols.

Returns:

all constellation symbols

class mokka.mapping.torch.GaussianDemapper(constellation)

Bases: Module

Classical Bitwise Soft Demapper with Gaussian Noise assumption.

Learns bias and covariance matrix of noise for constellation sorted from [0,2**m -1] and constructs a more or less efficient demapper which outputs LLRS for all m bits for each received symbol

__init__(constellation)

Construct GaussianDemapper.

forward(y, *args)

Perform bitwise demapping.

Params y:

Received complex symbols of dimension batch_size x 1

update_constellation(constellation)

Update saved constellation.

Params constellation:

Complex constellation symbols

warm_start(sym_idx, y, learning_fraction=0.3, single_circular=False)

Train covariance matrix with known symbols.

Params sym_idx:

Sent symbol index

Parameters:

  • y – Received complex symbols

  • learning_fraction – Learning rate

  • single_circular – Toggle if a a single sigma is learned for all symbols

class mokka.mapping.torch.MBPCSSampler(constellation_symbols, pcs_extra_params, fixed_lambda=False, l_init=None)

Bases: Module

This class is supposed to use NNs to find a lambda [0,1] for each given parameter (if given parameters) and then return p_symbols for further simulation.

Params constellation_symbols:

Complex constellation symbols

__init__(constellation_symbols, pcs_extra_params, fixed_lambda=False, l_init=None)

Construct MBPCSSampler.

forward(batchsize, *args)

Generate symbol indices.

Params batchsize:

Number of indices to generate

lambda_mb(*args)

Return currently trained lambda.

p_symbols(*args)

Return current probability distribution.

mokka.mapping.torch.MB_dist(lmbd, symbols)

Calculate the Maxwell-Boltzmann distribution for a given constellation.

Params lambda:

Lambda parameter of the Maxwell-Boltzmann distribution

Params symbols:

Complex constellation symbols

class mokka.mapping.torch.PCSSampler(m, l_init=None, symmetries=0, pcs_extra_params=None)

Bases: Module

Sample symbol indices from a learnable discrete probability distribution.

Params m:

bits per symbol

Params l_init:

Initial values for the per-symbol logits

Parameters:

symmetries – number of times the probabilty vector is repeated to obtain a probability distribution with uniform distribution for certain bits in the bitstring.

__init__(m, l_init=None, symmetries=0, pcs_extra_params=None)

Construct PCSSampler.

forward(batchsize, *args)

Generate symbol indices.

Params batchsize:

Number of indices to generate

p_symbols(*args)

Return current probability distribution.

class mokka.mapping.torch.QAMConstellationMapper(m)

Bases: Module

Non-trainable QAM constellation Mapper.

__init__(m)

Construct QAMConstellationMapper.

forward(b, *args)

Perform mapping of bitstrings.

Returns:

complex symbol per bitstring of length self.m

get_constellation(*args)

Return all constellation symbols.

Returns:

all constellation symbols

class mokka.mapping.torch.SeparatedConstellationMapper(m, m_real=None, m_imag=None, qam_init=False)

Bases: Module

Model to map complex and imaginary parts separately in two PAM modulations and add them after modulation.

Parameters:

  • m – bits per symbol

  • mod_extra_params – index of extra parameters to feed the NN

  • center_constellation – Apply operation at the end to center constellation

  • qam_init – Initialize the weights to form a Gray mapped QAM constellation

__init__(m, m_real=None, m_imag=None, qam_init=False)

Construct SeparatedConstellationMapper.

forward(b, *args)

Perform mapping of bitstrings.

Returns:

complex symbol per bitstring of length self.m

get_constellation(*args)

Return constellation for all input bits.

Params args:

same arguments as for forward() if constellation mapper is parametrized

Returns:

tensor of constellation points

static load_model(model_dict)

Load saved weights.

Parameters:

model_dict – dictionary loaded with torch.load()

class mokka.mapping.torch.SeparatedSimpleDemapper(m, demapper_width, demod_extra_params=())

Bases: Module

Simplified Demapper which approximates output LLRS of bits separated in real and imaginary parts.

Do simple function approximation with in -> Linear -> ReLU -> Linear -> out This should be easy to replicate in hardware with LUT

__init__(m, demapper_width, demod_extra_params=())

Construct SeparatedSimpleDemapper.

forward(y, *args)

Perform bitwise demapping of complex symbols.

Returns:

Approximated log likelihood ratio of dimension self.m

static load_model(model_dict, with_logit=True)

Load saved weights.

Parameters:

model_dict – dictionary loaded with torch.load()

class mokka.mapping.torch.SimpleConstellationMapper(m, qam_init=False)

Bases: Module

Mapper which maps using a simple list of weights and a one-hot vector.

Parameters:

m – bits per symbol

__init__(m, qam_init=False)

Construct SimpleConstellationMapper.

forward(b, *args)

Perform mapping of bits to symbols.

This mappper ignores all optional arguments as this Module is not parametrizable on call

Params b:

PyTorch tensor with bit vectors

Returns:

mapped constellation points

get_constellation(*args)

Return constellation for all input bits.

Params args:

same arguments as for forward() if constellation mapper is parametrized

Returns:

tensor of constellation points

static load_model(model_dict)

Load saved weights.

Parameters:

model_dict – dictionary loaded with torch.load()