Merge remote-tracking branch 'origin/Improve_link_test' into Channels

# Conflicts:
#	commpy/modulation.py

Author: BastienTr

README.md

@@ -54,6 +54,7 @@ Modulation/Demodulation
 - OFDM Tx/Rx signal processing
 - MIMO Maximum Likelihood (ML) Detection.
 - MIMO K-best Schnorr-Euchner Detection.
+- Convert channel matrix to Bit-level representation.
 
 Sequences
 ---------
@@ -66,7 +67,11 @@ Utilities
 - Hamming distance, Euclidean distance.
 - Upsample
 - Power of a discrete-time signal
+
+Links
+-----
 - Estimate the BER performance of a link model with Monte Carlo simulation.
+- Link model object.
 
 FAQs
 ----

commpy/examples/plotConsModem.py

@@ -0,0 +1,16 @@
+# Authors: Youness Akourim <akourim97@gmail.com>
+# License: BSD 3-Clause
+
+from commpy.modulation import PSKModem, QAMModem
+
+# =============================================================================
+# Example constellation plot of Modem
+# =============================================================================
+
+# PSK corresponding to PSKModem for 4 bits
+psk = PSKModem(16)
+psk.plotCons()
+
+# QAM corresponding to QAMModem for 2bits
+Qam = QAMModem(4)
+Qam.plotCons()

commpy/links.py

@@ -0,0 +1,147 @@
+# Authors: Youness Akourim <akourim97@gmail.com> & Bastien Trotobas <bastien.trotobas@gmail.com>
+# License: BSD 3-Clause
+
+"""
+============================================
+Links (:mod:`commpy.links`)
+============================================
+
+.. autosummary::
+   :toctree: generated/
+
+   link_performance     -- Estimate the BER performance of a link model with Monte Carlo simulation.
+   linkModel            -- Link model object.
+"""
+from __future__ import division  # Python 2 compatibility
+
+import numpy as np
+from commpy.channels import MIMOFlatChannel
+
+__all__ = ['link_performance', 'linkModel']
+
+
+def link_performance(link_model, SNRs, send_max, err_min, send_chunk=None, code_rate=1):
+    """
+    Estimate the BER performance of a link model with Monte Carlo simulation.
+
+    Parameters
+    ----------
+    link_model : linkModel object.
+
+    SNRs : 1D arraylike
+           Signal to Noise ratio in dB defined as :math:`SNR_{dB} = (E_b/N_0)_{dB} + 10 \log_{10}(R_cM_c)`
+           where :math:`Rc` is the code rate and :math:`Mc` the modulation rate.
+
+    send_max : int
+               Maximum number of bits send for each SNR.
+
+    err_min : int
+              link_performance send bits until it reach err_min errors (see also send_max).
+
+    send_chunk : int
+                  Number of bits to be send at each iteration.
+                  *Default*: send_chunck = err_min
+
+    code_rate : float in (0,1]
+                Rate of the used code.
+                *Default*: 1 i.e. no code.
+
+    Returns
+    -------
+    BERs : 1d ndarray
+           Estimated Bit Error Ratio corresponding to each SNRs
+    """
+
+    # Initialization
+    BERs = np.empty_like(SNRs, dtype=float)
+    # Set chunk size and round it to be a multiple of num_bits_symbol*nb_tx to avoid padding
+    if send_chunk is None:
+        send_chunk = err_min
+    divider = link_model.num_bits_symbol * link_model.channel.nb_tx
+    send_chunk = max(divider, send_chunk // divider * divider)
+
+    # Computations
+    for id_SNR in range(len(SNRs)):
+        link_model.channel.set_SNR_dB(SNRs[id_SNR], code_rate, link_model.Es)
+        bit_send = 0
+        bit_err = 0
+        receive_size = link_model.channel.nb_tx * link_model.num_bits_symbol
+        while bit_send < send_max and bit_err < err_min:
+            # Propagate some bits
+            msg = np.random.choice((0, 1), send_chunk)
+            symbs = link_model.modulate(msg)
+            channel_output = link_model.channel.propagate(symbs)
+
+            # Deals with MIMO channel
+            if isinstance(link_model.channel, MIMOFlatChannel):
+                nb_symb_vector = len(channel_output)
+                received_msg = np.empty_like(msg, int)
+                for i in range(nb_symb_vector):
+                     received_msg[receive_size * i:receive_size * (i+1)] = \
+                         link_model.receive(channel_output[i], link_model.channel.channel_gains[i], link_model.constellation)
+            else:
+                received_msg = channel_output
+            # Count errors
+            bit_err += (msg != received_msg).sum()  # Remove MIMO padding
+            bit_send += send_chunk
+        BERs[id_SNR] = bit_err / bit_send
+    return BERs
+
+
+class linkModel:
+    """
+        Construct a link model.
+
+        Parameters
+        ----------
+        modulate : function with same prototype as Modem.modulate
+
+        channel : _FlatChannel object
+
+        receive : function with prototype receive(y, H, constellation) that return a binary array.
+                    y : 1D ndarray
+                        Received complex symbols (shape: num_receive_antennas x 1)
+
+                    h : 2D ndarray
+                        Channel Matrix (shape: num_receive_antennas x num_transmit_antennas)
+
+                    constellation : 1D ndarray
+
+        num_bits_symbols : int
+
+        constellation : array of float or complex
+
+        Es : float
+             Average energy per symbols.
+             *Default* Es=1.
+
+        Attributes
+        ----------
+        modulate : function with same prototype as Modem.modulate
+
+        channel : _FlatChannel object
+
+        receive : function with prototype receive(y, H, constellation) that return a binary array.
+                    y : 1D ndarray of floats
+                        Received complex symbols (shape: num_receive_antennas x 1)
+
+                    h : 2D ndarray of floats
+                        Channel Matrix (shape: num_receive_antennas x num_transmit_antennas)
+
+                    constellation : 1D ndarray of floats
+
+        num_bits_symbols : int
+
+        constellation : array of float or complex
+
+        Es : float
+             Average energy per symbols.
+             *Default* Es=1.
+        """
+    def __init__(self, modulate, channel, receive, num_bits_symbol, constellation, Es=1):
+        self.modulate = modulate
+        self.channel = channel
+        self.receive = receive
+        self.num_bits_symbol = num_bits_symbol
+        self.constellation = constellation
+        self.Es = Es

commpy/modulation.py

@@ -15,23 +15,23 @@
    ofdm_rx              -- OFDM Receive Signal Processing
    mimo_ml              -- MIMO Maximum Likelihood (ML) Detection.
    kbest                -- MIMO K-best Schnorr-Euchner Detection.
+   bit_lvl_repr         -- Bit level representation
 
 """
 from itertools import product
 
+import matplotlib.pyplot as plt
+from commpy.utilities import bitarray2dec, dec2bitarray
 from numpy import arange, array, zeros, pi, cos, sin, sqrt, log2, argmin, \
     hstack, repeat, tile, dot, sum, shape, concatenate, exp, \
-    log, vectorize, empty
+    log, vectorize, empty, eye, kron
 from numpy.fft import fft, ifft
 from numpy.linalg import qr
 
-from commpy.utilities import bitarray2dec, dec2bitarray
-
-__all__ = ['PSKModem', 'QAMModem', 'ofdm_tx', 'ofdm_rx', 'mimo_ml', 'kbest']
+__all__ = ['PSKModem', 'QAMModem', 'ofdm_tx', 'ofdm_rx', 'mimo_ml', 'kbest', 'bit_lvl_repr']
 
 
 class Modem:
-
     def modulate(self, input_bits):
         """ Modulate (map) an array of bits to constellation symbols.
 
@@ -100,6 +100,44 @@ def demodulate(self, input_symbols, demod_type, noise_var=0):
 
         return demod_bits
 
+    def plotCons(self):
+        """ Plot the constellation """
+        # init some arrays
+        beta = self.num_bits_symbol
+        numbit = '0' + str(beta) + 'b'
+        Bin = []
+        mot = []
+        const = []
+
+        # creation of w array
+        reel = [pow(2, i) for i in range(beta // 2 - 1, -1, -1)]
+        im = [1j * pow(2, i) for i in range(beta // 2 - 1, -1, -1)]
+        w = concatenate((reel, im), axis=None)
+
+        listBin = [format(i, numbit) for i in range(2 ** beta)]
+        for e in listBin:
+            for i in range(beta):
+                Bin.append(ord(e[i]) - 48)
+                if (ord(e[i]) - 48 == 0):
+                    mot.append(-1)
+                else:
+                    mot.append(1)
+            const.append(dot(w, mot))
+            mot = []
+        symb = self.modulate(Bin)
+
+        # plot the symbols
+        x = symb.real
+        y = symb.imag
+
+        plt.plot(x, y, '+',linewidth=4)
+        for i in range(len(x)):
+            plt.text(x[i], y[i] , listBin[i])
+
+        plt.title('Constellation')
+        plt.grid()
+        plt.show()
+
 
 class PSKModem(Modem):
     """ Creates a Phase Shift Keying (PSK) Modem object. """
@@ -231,27 +269,35 @@ def kbest(y, h, constellation, K):
     -------
     x : 1D ndarray of constellation points
         Detected vector (length: num_receive_antennas)
+
+    raises
+    ------
+    ValueError
+                If h has more columns than rows.
     """
+    nb_tx, nb_rx = h.shape
+    if nb_rx > nb_tx:
+        raise ValueError('h has more columns than rows')
+
     # QR decomposition
     q, r = qr(h)
     yt = q.conj().T.dot(y)
 
     # Initialization
     m = len(constellation)
-    n = len(yt)
     nb_can = 1
 
     if isinstance(constellation[0], complex):
         const_type = complex
     else:
         const_type = float
-    X = empty((n, K * m), dtype=const_type)  # Set of current candidates
+    X = empty((nb_rx, K * m), dtype=const_type)  # Set of current candidates
     d = tile(yt[:, None], (1, K * m))        # Corresponding distance vector
     d_tot = zeros(K * m, dtype=float)        # Corresponding total distance
     hyp = empty(K * m, dtype=const_type)     # Hypothesis vector
 
     # Processing
-    for coor in range(n-1, -1, -1):
+    for coor in range(nb_rx-1, -1, -1):
         nb_hyp = nb_can * m
 
         # Copy best candidates m times
@@ -275,3 +321,29 @@ def kbest(y, h, constellation, K):
         d[:coor, :nb_can] -= r[:coor, coor, None] * hyp[argsort[:nb_can]]
         d_tot[:nb_can] = d_tot[argsort[:nb_can]]
     return X[:, 0]
+
+
+def bit_lvl_repr(H, w):
+    """ Bit-level representation of matrix H with weights w.
+
+    parameters
+    ----------
+    H   :   2D ndarray (shape : nb_rx, nb_tx)
+            Channel Matrix.
+
+    w   :   1D ndarray of complex (length : beta)
+            Bit level representation weights. The length must be even.
+
+    return
+    ------
+    A : 2D nbarray (shape : nb_rx, nb_tx*beta)
+        Channel matrix adapted to the bit-level representation.
+    """
+    beta = len(w)
+    if beta%2 == 0:
+        m, n = H.shape
+        In = eye(n,n)
+        kr = kron(In,w)
+        return dot(H,kr)
+    else:
+       raise ValueError('Beta must be even.')